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How to Use This Manual 



This manual is a guide to the interactive use of DATATRIEVE-11. It explains 
how to define dictionaries and dictionary objects (domains, records, tables, and 
procedures), and gives examples of using compound statements, command files, 
views, and hierarchies. It also discusses the restructuring of domains and the 
control of input and output. 

In this manual, the DATATRIEVE-11 software is referred to as DATATRIEVE. 

Intended Audience 

This manual is intended for people who: 

• Have read and tried the examples in the Introduction to DATATRIEVE-11 

• Have experience using DATATRIEVE 

• Have experience in applications programming but are unfamiliar with 
DATATRIEVE 

For people who have no experience with DATATRIEVE, the Introduction to 
DATATRIEVE-1 1 provides a tutorial to the basic D ATATRIE VE-1 1 tasks. 

Structure 

This manual is divided into 20 chapters, an appendix, and an index: 

Chapter 1 Introduces the basic concepts of DATATRIEVE-11. 

Chapter 2 Describes how to enter and exit DATATRIEVE, display data, use 
various prompts, and how to use DATATRIEVE Help and Guide 
mode. 

Chapter 3 Describes data dictionaries and how to create or change them. 
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Chapter 4 Describes how to name and define domains. 

Chapter 5 Describes how to plan a record definition, the rules governing the 
definition, the optional clauses you can use to specify certain con- 
ditions, and the use of lists to define hierarchical records. 

Chapter 6 Describes the difference between indexed and sequential data 

files, compares their advantages, and explains how to define them. 

Chapter 7 Discusses record selection expressions (RSEs) and how to use them 
to select particular records from your database. 

Chapter 8 Describes the use of REPEAT, FOR, and BEGIN-END blocks to 
combine statements into compound statements. 

Chapter 9 Describes how to define and use DATATRIEVE procedures. 

Chapter 10 Describes how to create and use DATATRIEVE command files. 

Chapter 11 Discusses DATATRIEVE variables, the differences between local 
and global variables, and how to use them. 

Chapter 12 Describes the creation and use of DATATRIEVE tables. 

Chapter 13 Describes how to define and use view domains to examine only 

part of one domain or to combine information from more than one 
domain. 

Chapter 14 Discusses how to use lists to retrieve data. 

Chapter 15 Explains how to change record and file definitions to restructure a 
domain. 

Chapter 16 Explains how to use the DATATRIEVE Editor. 

Chapter 17 Discusses the most effective ways of using your allotted work- 
space. 

Chapter 18 Describes ways to control the format of your output and how to use 
the SET ABORT and SET PROMPT commands. 

Chapter 19 Describes how to create, use, and maintain access control lists. 

Chapter 20 Describes how to modify and delete data dictionaries, optimize the 
disk storage space they use, and extract their contents. 

Appendix A Explains in detail the way DATATRIEVE establishes context, the 
context stacks, context variables, and single record context. 
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Related Manuals 

For further information on the topics covered in this manual, see: 

o Introduction to DATATRIEVE-1 1 

o DATATRIEVE-1 1 Call Interface Manual 

• DATATRIEVE-1 1 Reference Manual 

Conventions 

This section explains the special symbols used in this book: 
(ret) This symbol indicates the RETURN key. 

(Tab) This symbol indicates the TAB key. 

> The right angle bracket symbol at the beginning of a new line, or by 

itself, represents the system prompt. 

Color Color in examples shows user input. 

WORD Uppercase words represent DATATRIEVE keywords. 

word Lowercase words are generic terms that indicate entries you must 
provide. 

{ } Braces enclose clauses from which you must choose one alternative. 

[ ] Square brackets enclose optional clauses from which you can choose 

one or none. 

Horizontal ellipsis means you can repeat the previous item. 

Vertical ellipsis in an example means that information not directly 
related to the example has been omitted. 
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This chapter gives an overview of DATATRIEVE-11 and explains its basic con- 
cepts and terms. 

1 .1 Description of DATATRIEVE-1 1 

DATATRIEVE-11 is an interactive tool for inquiry, update, and maintenance of 
information stored in data files. DATATRIEVE-11 runs on any PDP-11 com- 
puter with an RSX-11M, RSX-11M-PLUS, RSTS/E, Micro/RSX, or Micro/RSTS 
operating system. 

The commands and statements you use are common English words that have 
specific meaning within DATATRIEVE. With these commands and statements 
you can manipulate the information in selected data files. 

1 .2 DATATRIEVE Concepts and Terms 

DATATRIEVE-11 uses concepts and terms that may not be familiar to you. 
These include: 

• Files, records, and domains 

• Data dictionaries 

• Commands and statements 

• Procedures 
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• Command files 

• Tables 

1.2.1 Files 

A data file contains ordered data. The DATATRIEVE DEFINE FILE command 
creates a data file and allows you to specify some of the characteristics of the file. 
You can use your record definition to control the way DATATRIEVE handles the 
data in other data files. You can also use a number of different record definitions 
to work with the information stored in one data file. 

1.2.2 Record Definitions 

The record is the basic unit of information management. It describes the rela- 
tionship between logically connected data items and consists of one or more 
subunits called fields. DATATRIEVE uses both elementary and group fields. An 
elementary field contains an item of data. A group field contains group and ele- 
mentary fields that are logically related. Thus, you might have an 
EMPLOYEE_NAME group field that contains the elementary fields 
FIRST_NAME, MIDDLE_INITIAL, and LAST-NAME . 

DATATRIEVE enables you to interpret the data in the fields of a data record. 
The DATATRIEVE record definition controls the way you look at and interpret 
the information coded in your data files. 

In the field definition clauses in a DEFINE RECORD command, you specify the 
type of field, the length of each field, and the content of the fields — character 
strings, numbers, or dates. You can also control the format DATATRIEVE uses 
to display values from those fields. 

Note that in field names (like FIRST_NAME), this manual uses underscores (_). 
When you are using DATATRIEVE, you may use either underscores or hyphens 
(-) in record or field definitions. DATATRIEVE accepts hyphens as input but con- 
verts them to underscores before analyzing user input. To use a hyphen as a 
minus sign, put spaces before and after it. Otherwise, DATATRIEVE converts 
the minus sign to an underscore and issues an error message. 

Be consistent in your own practice. To avoid confusion when using the manuals, 
you may want to use underscores instead of hyphens. Whichever you use, 
Chapter 5 of this manual explains record definitions and field definition clauses. 

1.2.3 Domains 

To manage the data in a file, you must explicitly connect that data file to a record 
definition. DATATRIEVE makes this connection with a domain. You use the 
DEFINE DOMAIN command to create a domain definition and to store that defi- 
nition in your current data dictionary. 
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The domain definition establishes a name for the domain and associates that 
name with the names of a record definition and a data file. When you use the 
name of the domain, you tell DATATRIEVE to use a particular record definition 
to interpret the data stored in a specific file. 

Do not confuse a domain with the data you want to manage. The data stored in 
the data file does not constitute the domain. You can erase old records and add 
new ones without disturbing the relationship between the data file and the 
record definition, which remains fixed. 

1 .2.4 Data Dictionaries 

A data dictionary is an RMS file that DATATRIEVE creates to store definitions. 
It stores tables, procedures, and the definitions of domains and records. 

1 .2.5 Commands and Statements 

You manage information with commands and statements based on the 
DATATRIEVE keywords described in this manual. 

Commands deal with the data dictionary and enable you to: 

o Create, change, and display definitions in the dictionary (DEFINE, SHOW, 
EDIT, DELETE, and EXTRACT) 

• Maintain the access control lists associated with those definitions (DEFINEP, 
SHOWP, and DELETEP) 

• Get access to domains (READY) 

• Release access to domains, variables, collections, and DATATRIEVE tables 
(RELEASE and FINISH) 

• Determine the way DATATRIEVE displays data on your terminal (SET) 

• Get online information about DATATRIEVE (HELP) 

• End your DATATRIEVE sessions (EXIT) 

Statements deal with data and enable you to: 
o Store records (STORE) 

• Form and manipulate groups of records (FIND, SELECT, DROP, and SORT) 

• Display data (PRINT, REPORT, and SUM) 

• Modify records (MODIFY) 

• Erase records (ERASE) 

• Declare variables and assign values (DECLARE and assignment) 
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You can join statements to form compound statements in the BEGIN-END, FOR, 
IF-THEN-ELSE, REPEAT, and THEN statements. You cannot join commands 
with other commands or with statements. Furthermore, only statements may 
contain DATATRIEVE value expressions and record selection expressions. 

You can enter statements at other levels than command level (indicated by the 
DTR> prompt), but you can enter commands only at command level. 

If you are not sure whether a given keyword is a command or a statement, refer 
to the table showing an alphabetical summary of commands and statements in 
the DATATRIEVE-1 1 Reference Manual. 

1.2.6 Procedures 

Most DATATRIEVE-1 1 applications involve sequences of commands and state- 
ments that you use again and again. To avoid retyping such a sequence, you can 
store it in your dictionary as a procedure. You can also use procedures within 
commands or statements. With the DEFINE PROCEDURE command, you give 
the sequence a name and enter both the name and the sequence into your dic- 
tionary. You invoke the procedure by entering a colon (:) and the procedure 
name. DATATRIEVE then interprets the content of the procedure just as though 
you had entered it at your terminal. 

1.2.7 Command Files 

You can use command files in DATATRIEVE in much the way you use 
DATATRIEVE procedures. The primary difference between the two is that you 
store command files in your operating system directory and procedures in a 
DATATRIEVE dictionary. 

When you invoke a command file, DATATRIEVE displays the text of the file on 
your terminal. When you invoke a procedure, however, the procedure definition 
is not displayed on your terminal. 

1.2.8 DATATRIEVE Tables 

DATATRIEVE tables perform two functions. They let you: 

• Specify one value and retrieve another that you have associated with the first 

• Validate data according to the presence or absence of a data item in the table 

A table contains pairs of character strings. The first member of each pair is the 
code string and the second is the translation string. The last entry in the table 
can be an ELSE clause that specifies a default translation string. Thus your 
table might match department codes (such as A01) with department names (such 
as Accounting). If you enter a code not in the table, for example, the ELSE clause 
can specify a message to be displayed on your terminal telling you the code is not 
valid. 
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DATATRIEVE-ll consists of four components on your PDP-11 system: 

• Interactive DATATRIEVE-ll 

The DTR.TSK task image allows you to access D ATATRIE VE at your 
terminal. 

• The DATATRIEVE-ll Distributed Server 

DDMETSK allows users on other DECnet nodes to use DATATRIEVE for 
accessing data files and data dictionaries on your node. 

• The DATATRIEVE-ll Call Interface 

The DTCLIB.OLB object module library allows application programs in other 
high-level languages to call DATATRIEVE subroutines. The calls, through a 
local or remote server, give you access to DATATRIEVE data files and 
dictionaries. 

• The DATATRIEVE-ll Remote Terminal Interface 

REMDTR.TSK is an interactive program that uses the Call Interface and the 
remote server. When you run REMDTR as a program, it looks as though you 
are running interactive DATATRIEVE on a remote node. 

The following sections describe these four components and tell you where to find 
information on each one. 

1 .3.1 Interactive DATATRIEVE 

When you invoke DATATRIEVE-ll on a PDP-11 system, you are running 
DTR.TSK, the interactive DATATRIEVE task image. This program accepts 
DATATRIEVE commands and statements from the terminal and uses the termi- 
nal as the default output device. DTR.TSK allows you to access data stored in 
disk files as well as definitions stored in one of the data dictionaries on your sys- 
tem, using DATATRIEVE commands and statements. The Introduction to 
DATATRIEVE-ll, the DATATRIEVE-ll Reference Manual, and this manual 
describe how to use interactive DATATRIEVE. 

1 .3.2 The DATATRIEVE Distributed Server 

The Distributed Data Manipulation Facility (DDMF), is also called the 
DATATRIEVE Distributed Server. It is a "slave" program. Another 
DATATRIEVE component sends it commands to execute, and it passes the 
results back to that component. DDMF can perform all the DATATRIEVE func- 
tions that DTR.TSK can perform, with the exception of the Application Design 
Tool (ADT) and Guide Mode. 
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You use the Distributed Server in three ways: 

• VAX DATATRIEVE uses the Distributed Server on a PDP-11 or VAX node to 
perform distributed operations. For example, when you type READY YACHTS 
AT FRODO in VAX DATATRIEVE, DATATRIEVE starts up DDMF on the 
node named FRODO and uses it to access definitions and data files on that 
node. 

• The D ATATRIE VE-1 1 Call Interface uses DDMF to give you access to data 
dictionaries and data files, allowing you to write application programs that 
call DATATRIEVE. 

• The D ATATRIE VE-1 1 Remote Terminal Interface uses DDMF through the 
Call Interface, allowing you to use your terminal to access DATATRIEVE on 
other nodes. 

1 .3.3 The D ATATRIE VE-1 1 Call Interface 

The Call Interface allows you to write high-level language programs that call 
DATATRIEVE, either on your own system or on another DECnet node. To use 
the Call Interface, you include calls to external DATATRIEVE subroutines in 
your program. When you build the task image, you link the program to the 
object module library DTCLIB.OLB. The subroutines pass information between 
the calling program and a local or remote DATATRIEVE Distributed Server. 
When you are running such a program, there are actually two task images 
active: 

• Your program linked to DTCLIB.OLB 

• DDMF, the DATATRIEVE Distributed Server that has been activated to serve 
your program 

Note 

You must have the DECnet software installed on your system 
before you can access DATATRIEVE on a remote node. 



The DATATRIEVE-11 Call Interface Manual tells you how to write programs 
that use the Call Interface. 

1 .3.4 The D ATATRIE VE-1 1 Remote Terminal Interface 

The DATATRIEVE-11 Remote Terminal Interface (REMDTR) gives you interac- 
tive access to DATATRIEVE on other nodes. 

Note 

You must have the DECnet software installed on your system 
before you can use REMDTR. 
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To use the Remote Terminal Interface on both RSTS and RSX-11M/M-PLUS 
systems, type RUN $REMDTR. If an error message is displayed, check with your 
system manager to make sure the program is installed. 

When REMDTR prompts you for a node name, you can type either a node name 
or a complete network address specification. The address specification includes a 
user name or account number and a password: 

Enter node name: M Y 1 J A X 

Enter node name: MY VAX " MYNAME PASWRD" 
Enter node name: MYRSTS " i 30 ,34 PASWRD " 

If you specify only the node name, you are logged in to the default DECnet 
account and may not have access to the data files or dictionaries you want. When 
you type the complete form of the specification, DECnet logs you into that 
account. 

After you have logged in successfully, you can use DATATRIEVE interactively 
on that node as if you were using DATATRIEVE on your own node, except that 
Guide Mode and ADT are not available. 

You can use the Remote Terminal Interface for copying dictionary definitions 
and data files across DECnet. It is also useful for testing a network path and 
determining the default characteristics of DDMF, the DATATRIEVE Distributed 
Server, on a remote node. 

For more information on using the Remote Terminal Interface, see the 
DATATRIEVE-1 1 Call Interface Manual. 
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Getting Started with DATATRIEVE 



This chapter tells you how to start and stop DATATRIEVE. It also tells you how 
to: 

• Work with sample domains, records, and files included in the 
D ATATRIE VE-1 1 installation kit 

• Use the PRINT and REPORT statements 

• Understand DATATRIEVE prompts 

• Interpret DATATRIEVE error messages 

• Use Help and Guide mode 

Invoking D ATATRIE VE-1 1 

The way you start DATATRIEVE can vary from one system to another. If you 
cannot invoke DATATRIEVE using the method discussed in this section, contact 
the person in charge of DATATRIEVE on your system. 

See your system manager for the exact invocation line for your system. Here is 
how to start the system if your invocation line is RUN $DTR: 

> RUN $DTR(ret) 

PDP-11 DATATRIEVE* DEC Query and Report System 
Version: V3.2» 13-N0V-87 
Type HELP for help 
DTR> 

The startup banner in the previous example shows you that you have success- 
fully invoked DATATRIEVE. 
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2.2 Sample Domains, Records, and Data Files 



The D ATATRIE VE-1 1 installation kit includes four sample domains: YACHTS, 
OWNERS, PERSONNEL, and FAMILIES. The domain definitions and the 
record definitions are in the system data dictionary. 

The following command creates a private dictionary for you called SAMPLE.DIC 
which resides in your current default directory. The command enters the domain 
and record definitions into the dictionary, and copies the data files into your 
directory. 

For RSTS/E and Micro/RSTS systems type: 

DTR> @LB: SETUP. DTR(reB 
DTR > 

For RSX, Micro/RSX, and VAX-11 RSX systems type: 

DTR > @LB: C 1 tZl SETUP, DTR(ret) 
DTR > 

To see that the sample domain and record definitions are in place, use the SHOW 
command: 

DTR > SHON DOMAINS » RECORDS© 
Domains: 

FAMILIES KETCHES OWNERS OWNERS-SEQUENTIAL 

PERSONNEL PERSONNEI SEQ SAILBOATS YACHTS 

YACHTS-SEQUENTIAL 

Records: 

OWNER-RECORD PERSONNEL-REC PERSONNEL_SEQ_REC 
YACHT 

DTR> 

The results of this command vary from one system to another, but you should be 
sure that D ATATRIEVE lists the needed domain and record definitions on your 
terminal. If you have difficulty, see the person responsible for DATATRIEVE-11 
on your system. 

2.3 QUERY.INI Startup File 

If you frequently start your D ATATRIEVE session with the same series of com- 
mands and statements, you can use a command file to execute the commands and 
statements automatically each time you invoke D ATATRIEVE. DATATRIEVE 
recognizes QUERY.INI as the default startup file. However, you can specify a dif- 
ferent startup file at installation time if you choose. 
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DATATRIEVE first looks for a QUERY.INI file in your default directory. If one is 
there, DATATRIEVE executes the commands and statements it contains before 
it accepts any other input. If you would like to be in Guide mode as soon as you 
invoke DATATRIEVE, for instance, you can include the SET GUIDE command 
at the end of your QUERY.INI file. You can put a SET DICTIONARY command 
in the QUERY.INI file to automatically change your default data dictionary. You 
can ready domains you use frequently. Your QUERY.INI file, then, might include 
these lines: 

SET DICTIONARY MYDIC.DIC 
SET GUIDE 
READY YACHTS 

When you type your command to invoke DATATRIEVE, you are placed in your 
own dictionary and in Guide mode, and the YACHTS domain is readied. 

Using READY, PRINT, and REPORT to Retrieve Data 

The basic keywords used to retrieve data are the READY command and the 
PRINT and REPORT statements. To display a complete domain, for example, 
first ready the domain. Then type PRINT followed by the domain name: 



DTR > READY PERSONNEL© 
DTR > PRINT PERSONNEL© 







FIRST 


LAST 






START 






SUP 


ID 


STATUS 


NAME 


NAME 


DEPT 




DATE 


SALARY 


ID 


00012 


EXPERIENCED 


CHARLOTTE 


SPIMA 


TOP 


12 


-Sep 


-72 


$75 


#892 


00012 


00891 


EXPERIENCED 


FRED 


HOWL 


Fl 1 


9- 


Ap r- 


7B 


$59 


♦ 594 


00012 


02943 


EXPERIENCED 


CASS 


TERRY 


D98 


o _ 


J a n - 


80 


$29 


,908 


39485 


12643 


TRAINEE 


JEFF 


TASHKENT 


C82 


4- 


Ap r- 


81 


$32 


#918 


87465 


32432 


TRAINEE 


THOMAS 


SCHWEIK 


Fl 1 


7- 


Nou- 


81 


$2G 


#723 


00891 


34456 


TRAINEE 


HANK 


MORRISON 


T32 


1- 


Mar- 


82 


$30 


#000 


87289 


38462 


EXPERIENCED 


BILL 


SWAY 


T32 


5- 


Mav- 


80 


$54 


#000 


00012 


38465 


EXPERIENCED 


JOANNE 


FREIBURG 


E4G 


20 


-Feb 


-80 


$23 


#908 


48475 


39485 


EXPERIENCED 


DEE 


TERRICK 


D98 


2- 


May- 


77 


$55 


#829 


00012 


48475 


EXPERIENCED 


GAIL 


CASSIDY 


E4G 


*? _ 


May- 


78 


$55 


#407 


00012 


48573 


TRAINEE 


SY 


KELLER 


T32 


•p _ 


A u sf - 


81 


$31 


#546 


87289 


49001 


EXPERIENCED 


DAN 


ROBERTS 


C82 


7- 


Jul- 


79 


$41 


#395 


87465 


49843 


TRAINEE 


BART 


HAMMER 


D98 


4- 


Au3- 


81 


$28 


#392 


39485 


78923 


EXPERIENCED 


LYDIA 


HARRISON 


Fl 1 


19 


- J u n 


-79 


$40 


#747 


00891 


837B4 


EXPERIENCED 


JIM 


MEADER 


T32 


4- 


Apr- 


80 


$41 


#029 


87289 


84375 


EXPERIENCED 


MARY 


NALEVQ 


D98 


3- 


Jan- 


76 


$56 


#847 


39485 


87289 


EXPERIENCED 


LOUISE 


DEPALMA 


G20 


28 


-Feb 


-79 


$57 


#598 


00012 


874B5 


EXPERIENCED 


ANTHONY 


IAC0B0NE 


C82 


2- 


J a n - 


73 


$58 


#482 


00012 


87701 


TRAINEE 


NATHANIEL 


CHONTZ 


Fl 1 


28 


-Jan 


-82 


$24 


#502 


00891 


88001 


EXPERIENCED 


DAM ID 


LITELLA 


G20 


1 1 


-No y 


-80 


$34 


#933 


87289 


90342 


EXPERIENCED 


BRUNO 


DONCHIKOV 


C82 


9- 


Au3- 


78 


$35 


#952 


87465 


91023 


TRAINEE 


STAN 


WITTGEN 


G20 


23 


-Dec 


-81 


$25 


#023 


87289 


99029 


EXPERIENCED 


RANDY 


PODERES IAN 


C82 


24 


-May 


-79 


$33 


#738 


87465 



DTR > 
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For an explanation of the various forms of the PRINT statement, see the Intro- 
duction to DATATRIEVE-1 1 and the DATATRIEVE-1 1 Reference Manual. To 
retrieve information in a report format, use the REPORT statement. This can 
provide you with a report title, a date, page numbers, and various statistical 
functions. In its simplest form, the report specification consists of a REPORT 
statement, followed by a PRINT statement specifying the fields you want to 
report, and an END-REPORT statement to conclude the specification: 

DTR > REPORT YACHTS WITH BUILDER = " ALBERG "(ret) 
RW> PRINT BOAT(RET) 
RW> END-REPORT© 

15-Nov-87 
Pase 1 



LENGTH 
OVER 

MANUFACTURER MODEL RIG ALL WEIGHT BEAM PRICE 

ALBERG 37 MK II KETCH 37 20*000 12 $36,951 

DTR > 

For a complete explanation of the DATATRIEVE-1 1 Report Writer, see the 
DATATRIEVE-1 1 Guide to Writing Reports. 

2.5 DATATRIEVE Input Line Prompts 

Several types of prompts provide you with information during your interactive 
DATATRIEVE session. There are four types of input line prompts: 

DTR> Marks the beginning of input lines and shows that DATATRIEVE is 
ready for your input 

CON> Prompts you to continue incomplete commands or statements and 
shows what DATATRIEVE expects next 

DFN> Prompts you to continue a partially complete DEFINE command 

RW> Prompts you to complete unfinished Report Writer statements and 
enter additional statements 
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DATATRIEVE Syntax Line Prompts 



When you press RETURN before completing a command or statement, 
DATATRIEVE prompts you with a phrase in square brackets telling you what 
sort of input it expects to satisfy the syntax of the command or statement. This 
example shows several of D ATATRIEVE's syntax prompts: 

DTR> READY© 

[Looking for Dictionary Element] 
CDN> YACHTS(ret) 
DTR> F I ND(retJ 

[Looking for "FIRST"* domain name* or collection name] 

CDN> YACHTS WITH© 

[Look in 3 for Boolean expression] 

CON> L0A(ret) 

[Looking for relational operator (eq t n t etc.)] 
CON> BETHEEN(ret) 

[Looking for a value expression] 
CDN> 20(ret) 

[Looking for upper value of between] 
C0N> AND© 

[Looking for a value expression] 

C0N> 30(RET) 

C 5 4 records found] 

DTR> 

2.7 DATATRIEVE Prompts for Storing and Modifying Values 

When you enter a STORE or MODIFY statement, DATATRIEVE usually 
prompts you to enter new information to be stored in the record, or to replace 
what was stored there previously. Unless the statement contains a USING 
clause, you are prompted to enter information for each field receiving a new 
value. The prompt is made up of the word "Enter" followed by the name of the 
field. It takes the following general form: 

Enter field-name: 

2.8 DATATRIEVE Error Messages 

Error messages are DATATRIEVE responses to faulty syntax or an error in 
logic. When it detects an error, DATATRIEVE displays an error message and 
returns you to DATATRIEVE command level. All data items remain the same as 
they were before you made the error. The messages describe the error. For 
instance, when you use an undefined name in a PRINT command, 
DATATRIEVE responds with an error message: 

DTR> PRINT RUBINS© 

Field "RUBINS" is undefined or used out of context 
DTR> 
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2.9 Ending Your DATATRIEVE Session 



You can exit from DATATRIEVE by: 

• Entering the EXIT command 

• Pressing CTRL/Z 

• Pressing CTRL/C two times 

2.9.1 Using the EXIT Command 

To end your DATATRIEVE session and return to the operating system command 
level, you can respond to the DTR> prompt with an EXIT command: 

D T R > EXITgET) 

Entering the EXIT command at any other DATATRIEVE prompt is a syntax 
error. 

2.9.2 Exiting from DATATRIEVE with CTRL/Z 

You can also end your DATATRIEVE session by entering CTRL/Z in response to 
the DTR> prompt: 

DTR> *Z 

Entering CTRL/Z in response to any prompt other than DTR> returns you to 
DATATRIEVE command level (DTR>). 

2.9.3 Exiting from DATATRIEVE by Pressing CTRL/C Two Times 

If you enter one CTRL/C when DATATRIEVE is executing a command, 
DATATRIEVE aborts its operation. If you enter CTRL/C two consecutive times, 
the second aborts the task and returns you to your operating system command 
level. Either the EXIT command or CTRL/Z is a better way to exit than two 
CTRL/Cs, because EXIT and CTRL/Z do not abort the task. 

2.10 Using Help 

DATATRIEVE offers two levels of help — basic and advanced. Basic help is infor- 
mation about elementary DATATRIEVE statements. Advanced help provides 
instructions on statements that you are likely to use after some experience with 
DATATRIEVE. To get information on the help topic itself, type HELP in 
response to the DTR> prompt. 

DTR> HELP© 
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For a listing of the topics for which help is available, type: 

DTR> HELP HEL P(ret) 

The topics of Greatest interest to the b e 3 i n n i n 3 user are 
the following: 



GUIDE 


READY 


FIND 


SORT 


PRINT 


MODIFY 


STORE 


EXIT 


Help is available for the 


following t n p i n ^ 1 




ABORT 


ADT 


ASSIGNMENT 


BEGIN 


COMPUTED 


CONDITION 


DATE 


DECLARE 


DEFINE 


DEFINEP 


DELETE 


DELETEP 


DICTIONARY 


DISPLAY 


DOMAIN 


DROP 


EDIT 


EDIT-STRING 


ERASE 


EXIT 


EXTRACT 


FILE 


FIND 


FINISH 


FOR 


GUIDE 


HELP 


IF 


MODIFY 


OCCURS 


PIC 


PRINT 


PROCEDURE 


RANGE 


READY 


RECORD 


RELEASE 


REPEAT 


REPORT 


RSE 


SELECT 


SET 


SHOW 


SHOWP 


SORT 


STORE 


SUM 


TABLE 


THEN 


USAGE 


VALUE 


VIEW 


DBMS 


OWNER 


WITHIN 





DTR > 



To get help on one of these topics, type HELP followed by the name of the topic 
and press the RETURN key. 



2.10.1 Using Advanced Help 

For a listing of topics for which advanced help is available, type: 

DTR > HELP ADVANCED HELP(RET) 

Advanced help is available for the following topics: 

CONDITION DICTIONARY DOMAIN DBMS 

EDIT EDIT-STRING FILE FIND 

MODIFY OCCURS PRINT PROCEDURE 

RANGE RECORD RSE SELECT 

SORT STORE TABLE USAGE 

VALUE VIEW 

DTR > 

To get advanced help on one of these subjects, type HELP ADVANCED followed 
by the name of the subject. 
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2.11 Guide Mode 

The self-explanatory Guide mode feature helps you: 

• While you are learning to use DATATRIE VE 

• Whenever you are unsure of the sequence of commands you need to accomplish 
your task 

Note 

To use Guide mode, you must have a video display terminal. It will 
not work on any hardcopy terminal. 



To get into Guide mode, type: 

DTR> SET GUIDE® 

DATATRIE VE then prompts you, step-by-step, for every operation you want to 
perform. If you need help, type a question mark (?). DATATRIE VE shows you a 
list of the possible commands and statements you can use to complete your task: 

DTR > SET GUIDE® 
Enter command* type ? for help 

If you type ?, the DATATRIEVE displays the following information: 

Enter command t type ? for help 

The possible responses are: 
READY Make domain available 

SHOW Display status information 

LEAUE Return to normal Datatrieue 

Notice that Guide mode automatically spells out entire words and phrases imme- 
diately after you type only one or two letters. You may find this somewhat star- 
tling at first, but you soon get used to it. Guide mode fills in the word as soon as 
you enter characters it recognizes. If you type R, it completes the word as 
READY. If you type RE, RE A, and so on, it also echoes the word READY. 

You can get unexpected results with Guide mode if you are not careful, however. 
For example, suppose you want to ready a domain called EASELS. If you 
type R EA, Guide mode does not expand the R to READY and the EA to 
EASELS. Rather, it interprets the EA as part of a READY command with 
no domain name supplied. To get the results you want, you could instead 
type REA EA, which would be expanded to READY EASELS. 

When you are ready to exit from Guide mode and return to regular 
DATATRIEVE, type LEAVE. The DTR> prompt means you are out of Guide 
mode. 
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Creating Data Dictionaries 



Each time you invoke it, DATATRIEVE automatically connects you to a data 
dictionary — an RMS file that DATATRIEVE creates to store definitions and pro- 
tection information. This chapter shows how to create a data dictionary. 

3.1 Contents of a Data Dictionary 

A data dictionary contains the definitions and protection information for the fol- 
lowing DATATRIEVE data structures: 

• Domains 

• Records 

• Procedures 

• Description tables 

Each definition describes the contents of the data structure: 

• A domain definition contains the name of the domain, the name of the record 
definition associated with the domain, and the file specification of the file con- 
taining the data for the domain. 

• A record definition contains the name of the record and a definition for each 
field in the record. 

• A procedure definition is the procedure itself, including the procedure name 
and all commands and statements in the procedure. 

• A table definition is the table itself, including its name and all code and 
description pairs. 
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Associated with each of these definitions is an access control list (ACL). It pro- 
tects the one definition with which it is associated and restricts its use. Access 
control lists supplement the protection features of your operating system. 

Creating a Data Dictionary 

You create a data dictionary using the DEFINE DICTIONARY command. The 
format of this command is: 

DEFINE DICTIONARY file-spec 

DEFINE DICTIONARY creates an empty indexed sequential RMS file that is 
suitable for use as a data dictionary. You supply the file specification, and the 
operating system creates an entry for it in your directory. You can choose any file 
extension when you create it. If you use the default file extension .DIC, you do 
not have to specify the file extension when referring to your dictionary file from 
DATATRIEVE command level. In addition, if you use the standard file exten- 
sion, you can easily identify your dictionary files when you list your directory. 

When you enter a DEFINE DICTIONARY command, DATATRIEVE creates a 
file and establishes the new dictionary as your current data dictionary, just as if 
you had entered a SET DICTIONARY command: 

DTR > SHOW D I CT I ONARY(RET) 

The current dictionary is SY : C 1 >3 ] NEWQ ♦ D I C 
DTR > DEFINE DICTIONARY MYDIC(ret) 
DTR > SHOW DICTIONARY® 

The current dictionary is SY : E 1 >37 ] MYD I C ♦ D I C 

Note that because you did not specify any extension for the dictionary, 
DATATRIEVE assigned .DIC by default. 

You can begin entering definitions immediately. If DATATRIEVE cannot create 
a file because, for example, you do not have write access to the disk, or the disk is 
not mounted, it prints a message on your terminal and leaves you connected to 
your current dictionary. 

Changing Dictionaries 

When you invoke it, DATATRIEVE automatically connects you to a default data 
dictionary. At the time of installation, your system manager determines what 
the default dictionary will be for your system. At the beginning of your 
DATATRIEVE session, that dictionary is your current dictionary. 

To find out the name of your current dictionary, use the following command: 

DTR > SHOW DICTIONARY© 

The current dictionary is SY : [ 1 >37 ] MYD I C ♦ D I C 

SHOW DICTIONARY prints the file specification of the current data dictionary. 
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If you want to use a different dictionary, use the following format of the SET 
command: 

SET DICTIONARY file-spec 

To change from the default dictionary to another dictionary, you must specify at 
least one element of the file specification of the other data dictionary. For exam- 
ple, if you specify only the device name, DATATRIEVE searches that device for a 
directory with your project-programmer number (PPN) or user identification 
code (UIC) and a file named QUERY.DIC. If DATATRIEVE does not find the file 
you specify, it prints an error message on your terminal and leaves you in your 
current dictionary. (At no time are you in DATATRIEVE without being in a data 
dictionary.) 

If you have readied a domain in your current dictionary and you change diction- 
aries, that domain is still available when you are in the new dictionary. This fea- 
ture allows you to move records from that readied domain into another domain 
in the new current dictionary. 

If you want to return to the default data dictionary, issue the SET DICTIONARY 
command without a file specification: 

DTR> SET DICTIONARY® 

The following dialogue illustrates the setting and displaying of data dictionaries. 
Note that if you try to set a dictionary that you have not defined, DATATRIEVE 
prints an error message on your terminal. You must first define the dictionary 
with a DEFINE DICTIONARY command. Note also that DATATRIEVE returns 
the DFN> prompt when you omit the file specification from the DEFINE 
DICTIONARY command. In this example, DR1: represents the name of the 
device on which the default DATATRIEVE system dictionary resides. DR2: is 
the name of the device on which your file directory is stored: 

DTR> SHOW DICTIONARY® 

The current dictionary is DR1:C1 >2HQUERY.DIC 

DTR > SET DICTIONARY NEWDIC® 

File "NEWDIC" not found 

DTR > DEFINE DICTIONARY® 

D F N > NEWDIC® 

DTR > SHOW DICTIONARY® 

The current dictionary is D R 2 : C 2 » 2 ] N E W D I C . D I C 
DTR > SET DICTIONARY® 
DTR > SHOW DICTIONARY® 

The current dictionary is DR 1 : [ 1 »2 ] QUERY . D I C 
DTR> 

Note that you do not need an explicit SET DICTIONARY command after enter- 
ing DEFINE DICTIONARY NEWDIC, because that DEFINE sets the dictionary 
to NEWDIC automatically. 
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Defining Domains 



When you define a DATATRIEVE domain, the domain associates the names of a 
record definition and a data file with each other. When you use a domain name, 
you tell DATATRIEVE to use a particular record definition to interpret the data 
stored in a specific file. 

Do not confuse the domain with the data you want to manage using the domain. 
You can erase old records or add new ones to a data file without disturbing the 
relationship between the file and a record definition. That relationship is estab- 
lished when you define a domain and it remains fixed. 

This chapter explains how to define simple RMS domains. You can also use the 
Application Design Tool (ADT) to define domains, records, and files. For informa- 
tion on using ADT, see the Introduction to DATATRIEVE-1 1 . 

Specifying Domain Names 

In the DEFINE DOMAIN command, you specify the name of a domain, the name 
of the record definition associated with the domain, and the file specification of 
the file containing the data for the domain. The domain name must: 

• Begin with a letter (A-Z) 

• Contain 31 characters or less 

• End with a letter (A-Z) or a digit (0-9) 

• Contain only letters, digits, dollar signs, hyphens, or underscores 
(A-Z, 0-9, $, -, or _) 
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DATATRIEVE enters the domain definition in your current dictionary directory. 



Note 



DATATRIEVE treats hyphens and underscores as identical char- 
acters. You may use either underscores or hyphens in the names 
you assign. When processing, DATATRIEVE automatically con- 
verts hyphens to underscores. When it returns the output, it shows 
underscores whether you have entered hyphens or underscores. To 
use a hyphen as a minus sign, put spaces before and after it. 



To define a domain, you associate the name of the domain with a record defini- 
tion and file specification. The format for the DEFINE DOMAIN command 
follows: 



The domain name cannot duplicate a DATATRIEVE keyword or the name of any 
other element in the current data dictionary. The record name refers to the 
record definition to be associated with the domain. You can define the domain 
before you define the record. (See Chapter 5 for information on defining records.) 

An optional password can be used to check for E (execute) privilege for the record 
definition. If an asterisk prompt (*) is specified, DATATRIEVE prompts you for 
the password. 

Be sure to end the definition with a semicolon (;). If you omit the semicolon, 
DATATRIEVE prompts you for one with DFN>. 

The following rules apply to the DEFINE DOMAIN command: 

• It must be preceded by a DATATRIEVE command level prompt DTR>. 

• You cannot include a domain definition in a procedure. 

• You cannot invoke a procedure in a domain definition. 

• You cannot include a DEFINE DOMAIN command in a DATATRIEVE 
statement. 

Here is an example of the DEFINE DOMAIN command: 

DTR> DEFINE DOMAIN SCHEDULE USING SCHED.REC ON SCHED !(ret) 
DTR> 

This command enters the definition for SCHEDULE in your current dictionary. 
The domain uses a record definition called SCHED_REC and a data file called 
SCHED.DAT. The file extension .DAT is assigned to the data file by default. 
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DEFINE DOMAIN domain-name USING record-name 
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Using the SHOW Command with Domains 



You can use the SHOW command to see how a domain is denned. If you enter 
SHOW followed by the domain name, the text you used in the DEFINE 
DOMAIN command is displayed on your terminal. For example, you enter 
SHOW SCHEDULE, as follows, to see how the domain SCHEDULE is denned: 

DTR > SHOW SCHEDULE© 
DOMAIN SCHEDULE 

USING SCHED-REC ON SCHED 5 
DTR > 

Note that the domain must be denned in your current default dictionary. (See 
Chapter 3 for information on dictionaries.) 

To see if a domain is in your dictionary, enter the SHOW DOMAINS command. 
This displays a listing of all domains in your default dictionary, as follows: 

DTR > SHOW DOMAINS© 
Domains: 

FAMILIES KETCHES OWNERS 

OWNERS_SEOUENTIAL SAILBOATS SCHEDULE 

YACHTS YACHTS_SEOUENTIAL 

DTR > 
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There are two ways to define a record in DATATRIEVE-11. You can use the 
interactive Application Design Tool (ADT), and DATATRIEVE creates the 
record for you based on your responses to a series of questions. You can also 
define the record yourself with the DEFINE RECORD command. 

For simple records, the Application Design Tool is often an efficient way to com- 
plete your definition. See the Introduction to DATATRIEVE-11 for a sample 
ADT session. The DEFINE RECORD command, on the other hand, lets you use 
options not available through ADT. For instance, it lets you include clauses such 
as the COMPUTED BY clause, which asks DATATRIEVE to calculate the value 
of a field from the values of other fields or value expressions. 

This chapter explains how to set up a record definition using the DEFINE 
RECORD command. The DATATRIEVE-11 Reference Manual contains addi- 
tional information on defining records, including alphabetical listings of all 
clauses you can use in your record definitions. 

Planning a Record Definition 

The first step in writing a DATATRIEVE record definition is to analyze your 
data. Decide what data items you need to manage, their relative importance, and 
ways to group related items. 

You might want to maintain your personnel files with DATATRIEVE, for exam- 
ple. As you analyze the information, you find that for each employee you want to 
include an identification number, status (experienced or trainee), name, depart- 
ment, starting date, salary, and supervisor identification number. Your list of 
data items might look like that in Figure 5-1. 
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IDENTIFICATION NUMBER 
STATUS 

EMPLOYEE NAME 
DEPARTMENT 
START DATE 
SALARY 

SUPERVISOR'S IDENTIFICATION NUMBER 
Figure 5-1 : Data Items in a Personnel Record 

With your DATATRIEVE installation kit, you receive a record called 
PERSONNEL-REC made up of the data items listed in Figure 5-1. The 
DATATRIEVE definition for that record appears in Figure 5-2. 

DTR > SHOW PERSDNNEL_REC(ret) 
RECORD PERSONNEL-REC 
USING 

01 PERSON . 
05 ID 

05 EMPLOYEE-STATUS 



05 EMPLOYEE-NAME 
10 FIRST-NAME 

10 LAST-NAME 

05 DEPT 
05 START-DATE 
05 SALARY 

05 SUP_ ID 

? 

DTR > 

Figure 5-2: PERSONNEL-REC Record Definition 

To write a DATATRIEVE record definition yourself, you provide the elements to 
transform a list of data items like that in Figure 5—1 into a formal record defini- 
tion like that in Figure 5-2. The rest of this chapter tells you how to make such a 
change. 

Getting Started and Naming a Record 

When you define a record, you begin by specifying the name of a record. You can 
define the record interactively by entering the DEFINE RECORD command 
at the DTR> prompt followed by the complete record definition. If you make 
a mistake, DATATRIEVE displays an error message and returns you to the 
DATATRIEVE command level without saving the definition. You must then 
retype it. 



PIC IS 9(5) . 
PIC IS X ( 1 1 ) 
QUERY-NAME IS STATUS 
QUERY-HEADER IS "STATUS" 

VALID IF STATUS EQ "TRAINEE" » "EXPERIENCED 1 
QUERY-NAME IS NAME. 
PIC IS X ( 1 ) 
QUERY-NAME IS F-NAME. 
PIC IS X ( 1 ) 
QUERY-NAME IS L-NAME, 
PIC IS X X X » 
USAGE IS DATE. 
PIC IS 9(5) 

EDIT-STRING IS $$$»$$$, 
PIC IS 9(5) , 
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To avoid retyping, you can define the record in a procedure (see Chapter 9) or a 
command file (see Chapter 10). You can define your record, or only a few fields of 
the record, complete the definition (remember the semicolon), and then revise it 
later. You can use your text editor or the DATATRIE VE Editor to add additional 
fields or make whatever other changes you would like. 

To make the changes with your text editor: 

1. Copy the record definition to a file, using the following statement: 
EXTRACT ON file-spec record-name 

2. EXIT from DATATRIE VE 

3. Use your text editor to make corrections in the record definition 

Notice the file begins with the commands DELETE record-name and 
DEFINE record-name. DATATRIEVE inserts these commands into the com- 
mand file when you use the EXTRACT command. When you invoke the file, 
DATATRIEVE deletes the incorrect record definition and creates the cor- 
rected one. 

4. Return to DATATRIEVE 

5. Execute the command file just created by typing the at sign (@) and the file 
name 

See Chapter 16 for a description of the DATATRIEVE Editor. 
When you name the record, the name must: 

• Begin with a letter (A-Z) 

• Contain 31 characters or less 

• Contain only letters, digits, dollar signs, hyphens, or underscores 
(A-Z, 0-9,$,-, or _) 

• Not duplicate a DATATRIEVE keyword 

• Not duplicate the name of an existing dictionary object 

5.3 Defining the Parts of a Record Definition 

Having named the record, you can define its parts. The complete record 
definition consists of one or more field definitions for fields like PERSON, 
EMPLOYEE_STATUS, and EMPLOYEE-NAME in Figure 5-2. Each field defi- 
nition describes the field itself, with a name and a field definition clause. It also 
describes the field's relationship to other fields, with a level number. Follow the 
definition with a period. Figure 5-3 shows the four parts of the SALARY field in 
PERSONNEL_REC. 
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Level 
Number 


Field 
Name 




05 


SALARY 


PIC IS 9(5) 

ED I T_STR I NG IS $$$ ,$$$|, 



-•-Two Field Definition Clauses 
— Period (.) 



Figure 5-3: Four Parts of the SALARY Field 

These are required parts of the field definition: 

• A level number specifying the field's relationship to other fields in the record 

• A field name identifying the field 

• A period (.) signifying the end of the field definition 

In addition, most field definitions contain clauses describing the information 
stored in the field. Among other things, field definitions can describe the size of a 
field, the type of information stored in it, and how the information will be 
displayed. 

In Figure 5-3, for example, the PIC (or PICTURE) clause describes the size of 
the SALARY field and the type of information which can be stored there, in this 
case a number with no more than five digits. The EDIT_STRING clause specifies 
that information in the SALARY field will be displayed in monetary format with 
a leading dollar sign ($) and a comma (,) in the appropriate place. 

Level numbers, field names, and field definition clauses are discussed in the fol- 
lowing sections. 

5.3.1 Specifying Level Numbers 

DATATRIEVE recognizes the levels of fields in the record definition according to 
the level numbers you assign. The level number is the first element of a field 
definition. Level numbers are one- or two-digit numbers, ranging from the high- 
est possible level, 1, to the lowest possible level, 65. Leading zeros, as in 01 or 05, 
do not affect the value of the level number. 

Figure 5—4 shows the level numbers for fields in the PERSONNEL record 
definition. 



01 PERSON 
05 ID 

05 EMPLOYEE-STATUS 
05 EMPLOYEE-NAME 

10 FIRST-NAME 

10 LAST-NAME 
05 DEPT 
05 START-DATE 
05 SALARY 
05 SUP_ID 

Figure 5-4: Level Numbers in the PERSONNEL Record Definition 
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The level numbers apply to each group and elementary field: 

• Group fields contain one or more group or elementary fields. 

• Elementary fields contain one item of data and no other fields. 

The group field PERSON is the top-level field and the only field with the level 
number 01. Every record must have a top-level field. The group field 
EMPLOYEE-NAME, numbered 05, contains the elementary fields 
FIRST-NAME and LAST-NAME, numbered 10. The remaining fields, num- 
bered 05 like the group field EMPLOYEE-NAME , are elementary fields at the 
same level as EMPLOYEE-NAME. 

If one of the elementary fields numbered 05 (DEPT, for example), were numbered 
06, then that field would no longer be at the same level as the group field preced- 
ing it. If DEPT were numbered 06, then it would become a part of the group field 
EMPLOYEE-NAME. 

A group field is not just a marker of record structure and relationships among 
data items. A group field also gives you a way of using one name to refer to more 
than one field. You can access all the data in the PERSONNEL-REC record, for 
example, by using the group field PERSON. The following example shows how 
you can display all the data in a selected record in the PERSONNEL domain 
using the PERSON group field in a PRINT statement: 

DTR > READY PERSONNEL© 
DTR> FIND PERSONNEL© 
C 2 3 records found] 
DTR > SELECT 3© 
DTR > PRINT PERSON© 

FIRST LAST START SUP 

ID STATUS NAME NAME DEPT DATE SALARY ID 

02943 EXPERIENCED CASS TERRY D98 2-Jan-SO $29*908 39485 

DTR > 

When you develop a record structure, keep in mind these four guidelines for 
using group and elementary fields: 

• A record definition must define at least one elementary field. 

• A record definition with more than one field definition must define a top-level 
group field that includes all other fields in the record. 

• A group field must contain at least one elementary field. 

• A group field can contain both elementary and group fields. 
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Following are several rules for level numbers: 

• Level numbers need not be consecutive. 

Only the relative value of level numbers determines the relationship between 
fields. For example, the structure of the record would be no different from its 
present form if the fields numbered 05 had level numbers 02, and 
FIRST-NAME and LAST_NAME had level numbers 47. Using similar incre- 
ments in the numbers of successive levels is convenient but arbitrary. You do 
not have to use the same increment between levels. 

• Only the level numbers determine the relationships among fields. 

The examples of records in this book indent field names to show the relation- 
ships among levels of fields. Although indenting fields can make a record defi- 
nition easy to read, it has no effect on the levels of fields and no effect on the 
relationships between fields. 

• You must use one number for all the fields at the same level in a group field, 
like FIRST_NAME and LAST_NAME in PERSONNEL_REC. 

• The level number for a group field must be lower than the number for any field 
it contains. 

5.3.2 Naming Fields 

You must name every field you define. You use field names to control the way 
DATATRIEVE retrieves, modifies, and stores data. If you do not specify a column 
header different from the field name, DATATRIEVE uses the field name as the 
column header when displaying data. 

5.3.2.1 Restrictions for Field Names — The names you choose for fields must con- 
form to the general restrictions for DATATRIEVE names, described in the 
DATATRIEVE-11 Reference Manual. In summary, the name: 

• Can consist of letters, digits, hyphens, dollar signs, and underscores 

• Must begin with a letter 

• Must not duplicate a DATATRIEVE keyword 

• Must be from 1 to 31 characters long 

• Must not duplicate the name of another dictionary object, domain, procedure, 
or table 

In most cases, DATATRIEVE displays an error message if you violate these 
rules. However, if you duplicate dictionary object names, you may not receive an 
error message or you may get unexpected results. For example, suppose you 
want to display the contents of a field with the same name as a readied domain 
in your workspace. If you enter PRINT and the field name, DATATRIEVE asso- 
ciates the name with the domain rather than the field and displays the contents 
of the domain. DATATRIEVE associates the name with the field only if it is the 
second name in a print list. 
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You can continue a name from one input line to another by typing a hyphen at 
the end of the input line, pressing RETURN, and completing the name on the 
next line. To make the original information for the PERSONNEL record (Figure 
5—1) conform to the rules for field names, change some of them. None of the 
names in the original information exceeds 30 characters, but several contain 
spaces, which are illegal characters in DATATRIEVE names. Figure 5-5 shows 
the necessary changes. 



IDENTIFICATION 
STATUS 

EMPLOYEE NAME 



DEPARTMENT 
START DATE 

SUPERVISOR'S IDENTIFICATION NUMBER 



ID 

EMPLOYEE-STATUS 
EMPLOYEE-NAME 

FIRST-NAME 

LAST-NAME 
DEPT 

START-DATE 
SUP-ID 



Figure 5-5: Valid Field Names for EMPLOYEE-REC 



5.3.2.2 Using Duplicate Field Names — DATATRIEVE does not require field 
names to be unique. You can have several fields in one record that have the same 
name. However, fields that share one name must be in different group fields. To 
refer to a field name that is a duplicate, prefix it with its group field name. The 
record is a field tree, not a simple linear list. No other field is equivalent to the 
top-level field. All other fields are at lower levels of the structure. The levels of 
the field tree define the relationships among group and elementary fields and 
determine the sequence DATATRIEVE follows in searching for the names of 
fields. In PERSONNEL_REC, the fields ID, EMPLOYEE-STATUS, 
EMPLOYEE_NAME, DEPT, START-DATE, SALARY, and SUP_ID are at the 
same level, one level below the top-level PERSON. FIRST_NAME and 
LAST_NAME are on the third level in the field tree. 

The following examples show some consequences of this structure: 

• If you specify EMPLOYEE_NAME.LAST_NAME, DATATRIEVE looks at the 
field names in the group field EMPLOYEE-NAME until it finds the desired 
field. When DATATRIEVE searches for the specified field, it finds the first field 
named EMPLOYEE-NAME. Then it looks at the next level lower for the first 
field named LAST-NAME. 

DTR > FIND PERSONNEL© 
E 2 3 records found] 
DTR > SELECT 3(ret) 

DTR > PRINT ID> EMPLOYEE-NAME . LAST_NAME > SALARY© 
LAST 

ID NAME SALARY 

02943 TERRY $29 ,908 

DTR > 
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If you had a duplicate field called LAST_NAME, perhaps under a group field 
SUP_NAME, you could use the tree structure to tell DATATRIEVE whether 
you wanted to print EMPLOYEE-NAME. LAST_NAME or 
SUP_NAME .LAST_NAME . 

• LAST-NAME, without any qualification, is also a valid and unique field name 
in PERSONNEL-REC because there is no duplicate for it in the present 
record. 

• If you tell DATATRIEVE to store a value in ID. FIRST-NAME, it does not find 
the field FIRST-NAME and does not store the value. It displays an error mes- 
sage that says: 

Field " ID . FIRST-NAME" is undefined or used out of context 

In general, though you can have duplicate and even multiple field names, it is 
best to avoid duplicates. Unless you provide a qualified field name when refer- 
ring to a duplicate field, DATATRIEVE retrieves the value of the first instance of 
the duplicate field name. If you intend to refer to an instance other than the first 
but do not specify it, you will receive the output of the first instance instead of 
what you intend. If you do choose to use duplicate or multiple field names, you 
should be careful to use qualified names when necessary. 

5.3.2.3 Using the Field Name FILLER — Sometimes you want to preserve fields in 
a data file without using them, usually for one of these reasons: 

• You may not need those fields for a particular application. 

• You may want to control the display of records so that you do not display cer- 
tain data. 

• You may want to reserve space in the physical record of the data file. 

For these purposes, you can specify the keyword FILLER as the name of an ele- 
mentary or group field. Like other fields, a field named FILLER must have a 
level number, and it can contain field definition clauses. Unlike other fields, the 
field name FILLER can belong to more than one field at the same'level in a 
group field. When you use the PRINT, LIST, MODIFY, STORE, REPORT, and 
SUM statements, DATATRIEVE ignores values in FILLER fields. When you use 
the DISPLAY statement, DATATRIEVE does display the values in FILLER 
fields. 

You cannot retrieve whole records or group fields containing a group field named 
FILLER. You can, however, retrieve values from the elementary and group fields 
included in a group field named FILLER. Each of those fields has its own valid 
name, and you can retrieve the value by specifying that name in a record selec- 
tion expression, a print list, or a field list. 

Figure 5-6 shows a part of the YACHT record definition with FILLER in place of 
TYPE, the group field that contains MANUFACTURER and MODEL. It also 
shows the result of a SHOW FIELDS and two PRINT statements, one of the top- 
level group field and one of an elementary field (MODEL) in the group field 
FILLER. 
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Level numbers and field names of YACHT record with filler as group field 



01 BOAT 

03 FILLER 

06 MANUFACTURER 

0G MODEL 
03 SPECIFICATIONS 

OB RIG 

OG LENGTH_O l ,'ER_ALL 
OG DISPLACEMENT 
OG BEAM 
OG PRICE 

The effect of FILLER on SHOW FIELDS 



DTR > SHOW FIELDS® 
YACHTS 
BOAT 

SPECIFICATIONS (SPECS) 

RIG [Character string] 

LENGTH_OVER_ALL (LOA) [Character string] 
DISPLACEMENT (DISP) [Number] 
BEAM [Number] 
PRICE [Number] 

DTR > 

The effect of FILLER as a group field on two PRINT statements 



DTR> FIND YACHTS! SELECT ? PRINT© 

LENGTH 
OVER 

RIG ALL WEIGHT BEAM PRICE 
KETCH 37 20*000 12 $36,951 
DTR > PRINT MODEL© 

MODEL 
37 MK II 
DTR > 



Figure 5-6: Using FILLER as a Group Field Name 
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5.3.3 Using Field Definition Clauses 

DATATRIE VE handles the information in a field according to the type of data in 
the field definition. DATATRIEVE recognizes the following field definition 
clauses: 

• COMPUTED BY 

• EDIT_STRING 

• OCCURS 

• PICTURE 

• QUERY-HEADER 

• QUERY-NAME 

• REDEFINES 

• SIGN 

• USAGE 

• VALID IF 

When you write a DATATRIEVE record definition, use a PICTURE, USAGE, or 
COMPUTED BY clause to specify the type of data each elementary field 
contains. 

You can specify these classes of fields: 

• Alphanumeric 

Define an alphanumeric field with a PICTURE clause of the form PIC X(n), 
where n is an integer value describing the field width. The 
EMPLOYEE-STATUS field in the record PERSONNEL_REC, for instance, 
looks like this: 

05 EMPLOYEE-STATUS PIC IS X ( 1 1 ) . 

You can store any combination of characters in alphanumeric fields: letters, 
digits, and the special characters that are part of the DATATRIEVE character 
set. See the DATATRIEVE-1 1 Reference Manual for a definition of the 
DATATRIEVE character set. 
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• Numeric 

You can store digits and an optional sign ( + or -) in numeric fields. 
DATATRIEVE assumes unsigned numbers to be positive in computations. In 
the YACHT record, DISPLACEMENT, BEAM, and PRICE are numeric fields. 
Define a numeric field with a PICTURE clause of the form PIC (n), where n is 
an integer value representing the field width, or with any of these USAGE 
clauses: 

- COMP (or INTEGER) 

- COMP-1 (or REAL) 

- COMP-2 (or DOUBLE) 

- COMP-3 (or PACKED) 

- COMP-5 (or ZONED) 

USAGE clauses follow a field definition in the format: 

OG EMPLOYEE-SALARY PIC IS 9(6) USAGE IS INTEGER . 

See the DATATRIEVE-1 1 Reference Manual for explanations of the internal 
storage for USAGE clauses. 

• Date 

Define a date field with the USAGE clause in the form USAGE IS DATE. You 
can store dates between 17-Nov-1858 and 28-Feb-2100 in a date field. You can 
use the values in date fields in some kinds of computations. For example, you 
can subtract one date from another to get the number of days elapsed between 
the two dates. 

• Computed by 

Define a computed by field with the COMPUTED BY clause. A computed by 
field in a record definition does not correspond to a field in the physical record 
stored in the data file and does not occupy space in a record. It specifies a value 
expression. For example, you can define a field named SALARY computed by 
multiplying the hourly pay of an employee (the WAGE field of the same record) 
by the number of hours worked (the HOURS field of the record). The field defi- 
nition would be: 

05 SALARY 

EDIT-STRING $$$9.39 
COMPUTED BY WAGE * HOURS ♦ 

DATATRIEVE computes the value of the field when you refer to it in a 
statement. 
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An elementary field can belong to any one of the four classes of fields — alphanu- 
meric, numeric, date, or computed by. You do not need to use a clause to specify 
the data type for a group field. A group field is always alphanumeric. If you have 
stored only digits in a group field, you can use it in arithmetic computations. 

Table 5-1 summarizes the field classes and their content. 



Table 5-1 : Field Classes 



Field Type 


Class 


Content 


Elementary field 


Alphanumeric 


Any combination of characters 




Numeric 


Any combination of digits and optional plus ( + ) or 
minus ( — ) sign 




DATE 


A date 




COMPUTED BY 


None; the field definition specifies a value expres- 
sion, but no value is stored in the record 


Group field 


Alphanumeric 


The values of the fields contained in the group field 



5.3.4 Specifying Query Names 

You can use the QUERY-NAME field definition clause to specify an alternative 
name for any field in your record definition. When you name a field, it is good to 
select a field name that is short enough to use easily but long enough to be mean- 
ingful, especially to other people who may use the record. At times, however, you 
may want to use an abbreviation or a memorable short name in place of the for- 
mal field name. For example, the YACHT record contains one field named 
LENGTH_OVER_ALL that is fifteen characters long. The name suggests the 
meaning of the data stored in that field and is therefore helpful to a person unfa- 
miliar with the YACHTS domain. The field has a query name as well, LOA, to 
save you from having to type the complete name each time you refer to the field. 

You can use a query name in any D ATATRIEVE statement where you can use 
the corresponding field name. Figure 5-7 shows a set of query names for 
PERSONNEL_REC , 



EMPLOYEE-STATUS QUERY-NAME IS STATUS. 

EMPLOYEE-NAME QUERY-NAME IS NAME. 

FIRST-NAME QUERY-NAME IS F-NAME. 

LAST-NAME QUERY-NAME IS L-NAME. 

Figure 5-7: Query Names for PERSONNEL-REC 
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5.3.5 Specifying Word Boundary Alignment with the ALLOCATION 
Clause 

The ALLOCATION clause determines which word boundary alignment 
DATATRIEVE uses when storing records in the data file. You can specify one of 
three kinds of alignment: 

• LEFT-RIGHT 

• MAJOR-MINOR 

• ALIGNED_MAJOR_MINOR 

For explanations of the three word boundary alignments, see the 
DATATRIEVE-1 1 Reference Manual. If you do not specify otherwise, 
D ATATRIE VE-1 1 uses LEFT_RIGHT alignment. 

If you attempt to use DATATRIEVE-1 1 on a data file created with an alignment 
other than LEFT-RIGHT, be sure to specify the matching alignment in the 
DATATRIEVE-1 1 record definition. VAX DATATRIEVE, for instance, uses 
MAJOR-MINOR as the default alignment. You must specify MAJOR-MINOR 
in your DATATRIEVE-1 1 record definition if you wish to use a data file created 
on VAX DATATRIEVE. If the alignment in the record definition does not match 
the alignment in the data file, you receive this message: 

File and domain record lengths don't match ( D = 5 7 ) 

Using the OCCURS Clause to Define Hierarchical Records 

At times, to save space in your record definition, you may want to define one or 
more fields as list fields. Compare, for instance, the following two sample output 
lines from the domain FAMILIES. The first does not use a list field but instead 
includes a separate field in the record for each child. The second does use a list 
field: 

DTR> PRINT FIRST 1 FAMILIES® 

KID KID 
FATHER MOTHER NAME AGE NAME AGE 

JIM ANN URSULA 7 RALPH 3 

DTR> 



DTR> PRINT FIRST 1 FAMILIES© 

NUMBER KID 
FATHER MOTHER KIDS NAME AGE 

JIM ANN 2 URSULA 7 

RALPH 3 

DTR> 
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Records without lists are flat records, because the elementary fields in them are 
logically equivalent to each other. When you print a flat record, all the elemen- 
tary fields display on the same line. 

Without an OCCURS clause, the record for FAMILIES can look like the one 
shown in Figure 5-8. 



01 FAM I LY-REC ♦ 
03 PARENTS. 

OB FATHER PIC X( 10) . 
OG MOTHER PIC X( 10) . 
03 KIDS. 

0G F I RST_K I D . 

09 K ID-NAME PIC X( 10) . 
09 AGE PIC 99 ED I T_STR I NG IS Z9. 
0G SECOND_KID. 

09 K ID-NAME PIC X( 10) . 

09 AGE PIC 99 ED I T_STR I NG IS Z9. 



Figure 5-8: A Flat Record 



When using an OCCURS clause, however, you can define a record with fields 
that are lists. A record containing a list or lists is not a flat record, but a 
hierarchical record. In hierarchical records, elementary fields are not all logi- 
cally equivalent to each other. The list field displays on the same line as the ele- 
mentary fields with the same number, but the list items display on additional 
lines beneath the list field. With an OCCURS clause for KIDS, the record 
FAMILY JREC can look like the one in Figure 5-9, a sample record installed 
with your system. 



DTR > SHOW FAMILY_REC(ret) 
RECORD FAMILY _REC 
01 FAMILY. 

03 PARENTS. 

0G FATHER PIC X( 10) . 
0G MOTHER PIC X< 10) . 
03 NUMBER_K I DS PIC 99 EDIT-STRING IS Z9 . 

03 KIDS OCCURS TO 10 TIMES DEPENDING ON NUMBER-KIDS. 
0G EACH-K I D . 

09 K I D_NAME PIC X(10) QUERY -NAME IS KID. 
09 AGE PIC 99 ED IT-STRING IS Z9. 



Figure 5-9: A Hierarchical Record 



The OCCURS clause in the record definition creates the hierarchical structure. 
The clause can define a variable-length or a fixed-length list. The following two 
sections discuss fixed-length and variable-length lists for hierarchical records. 
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5.4.1 Defining Lists with a Fixed Number of Occurrences 

The OCCURS clause format for fixed length lists is OCCURS n TIMES, where n 
is the number of occurrences. If you define the record for FAMILIES using 
OCCURS 2 TIMES, the record definition looks like this: 

03 K IDS-NAMES OCCURS 2 TIMES. 
05 F I RST_NAME PIC X< 10) . 
05 AGE PIC 93 ED I T_STR I NG IS Z9. 

The definition specifies that the group field KIDS_NAMES occurs twice. Each 
occurrence of KIDS_NAMES contains two fields, FIRST-NAME and AGE. 

When DATATRIEVE displays the fixed record, the output looks like this: 

DTR > PRINT FIRST 2 FAMILIES© 

FIRST 
NAME 



FATHER 


MOTHER 




AGE 


JIM 


ANN 


URSULA 


7 






RALPH 


3 


JIM 


LOUISE 


ANN 


31 






JIM 


29 



DTR > 

You can use OCCURS n TIMES with an elementary or group field, and a record 
definition can contain any number of OCCURS clauses in this format. That is, an 
OCCURS clause can contain another fixed-length OCCURS clause. 

03 K I DS_NAMES OCCURS 2 TIMES 
05 FIRST-NAME PIC X < 1 ) . 
05 AGE PIC 99 ED I T_STR I NG IS Z9 . 
05 NICKNAME PIC X( 10) 
OCCURS 3 TIMES ♦ 

If you define a hierarchical record with a list that occurs a fixed number of times, 
every record in the domain contains enough space to store the same number of 
list items. If the first two families had only one child, for instance, the FAMILIES 
domain with a fixed number of occurrences would print a blank line for the sec- 
ond child: 

DTR> PRINT FAMILIES© 

FIRST 
NAME 

FATHER MOTHER AGE 

JIM ANN URSULA 7 



JIM LOUISE ANNE 31 



DTR > 
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A field definition cannot contain both an OCCURS and a COMPUTED BY 
clause. That is, you cannot specify multiple occurrences of a COMPUTED BY 
field. 

5.4.2 Defining Lists with a Variable Number of Occurrences 

Using the OCCURS clause in a field definition defines a hierarchical record that 
allows a variable number of list items from one record to another. This format 
lets you vary the number of list items in the records of a domain: 

OCCURS min TO max TIMES DEPENDING ON field-name 

The record definition for FAMILIES uses the OCCURS clause to define KIDS as 
a variable-length list. The KIDS variable-length list for FAMILY_REC is shown 
in Figure 5-9. The output of the PRINT command shows the relationship 
between NUMBER_KIDS and the fields KID_NAME and AGE. The values of 
KID_NAME and AGE appear as a list in records with more than one kid: 



DTR > PRINT FAMILIES© 







NUMBER 


KID 




FATHER 


MOTHER 


KIDS 


NAME 


AGE 


JIM 


ANN 


<-j 


URSULA 


7 








RALPH 


3 


JIM 


LOUISE 


5 


ANNE 


31 








JIM 


29 








ELLEN 


2G 








DAU ID 


za 








ROBERT 


IS 


JOHN 


JULIE 




ANN 


29 








JEAN 


2G 


JOHN 


ELLEN 


1 


CHRISTOPHR 





ARNIE 


ANNE 




SCOTT 


2 








BRIAN 





SHEARMAN 


SARAH 


1 


DAU ID 





TOM 


ANNE 




PATRICK 


a 








SUZIE 


6 


BASIL 


MERIDETH 


G 


BEAU 


28 








BROOKS 


2G 








ROBIN 


2a 








JAY 


*? *? 








WREN 


17 








JILL 


20 


ROB 


DIDI 









JEROME 


RUTH 


a 


ERIC 


32 








CISSY 


2a 








NANCY 


*?? 








MICHAEL 


20 


TOM 


BETTY 


<-> 


MARTHA 


30 








TOM 


27 


GEORGE 


LOIS 


3 


JEFF 


23 








FRED 


26 








LAURA 


21 


HAROLD 


SARAH 


3 


CHARLIE 


31 








HAROLD 


35 








SARAH 


27 


EDWIN 


TRINITA 




ERIC 


1G 








SCOTT 


1 1 



DTR > 



5-16 Defining Records 



When you define a record with a variable-length list in it, you must put the list 
at the end of the record definition. You can use only one field with an OCCURS 
clause. That is, you cannot have an OCCURS clause within an OCCURS clause. 
If you attempt to define another field after an OCCURS clause and at the same 
level, you receive the following error message: 



ONLY Subordinate fields allowed after OCCURS DEPENDING ON 



5.4.3 Nesting Lists Within Lists to Form Sublists 

Although you can use only one OCCURS clause in a record definition, you can 
define fixed-length lists within a variable-length list. In fact, you can include 
any number of OCCURS n TIMES clauses within a field defined with an 
OCCURS clause. This sample record definition with a sublist is an extension of 
the FAMILY record. The list PET occurs twice for each kid, so each kid in each 
family can record the data for two pets: 



DTR > SHOW PETS© 
DOMAIN PETS 

USING PET_REC ON PET . DAT j 

DTR > SHOW PET-REC© 
RECORD PET-REC 
01 FAMILY ♦ 

03 PARENTS . 



OS FATHER PIC X< 10) . 












OS MOTHER PIC X( 10) . 












03 NUMBER_K I DS PIC 99 EDI 


T-STRING 


IS 


Z9. 






03 KIDS OCCURS TO 10 TI 


MES DEPENDING ON 


NUMBER. 


.KIDS. 


OB EACH-KID* 












09 K I D_NAME PIC X ( 1 


0) QUERY. 


.NAME IS 


KID. 




09 KID_AGE PIC 99 E 


D I T_STR I NG 


IS 29 






09 PET OCCURS 2 TIM 


ES. 










13 PET_NAME PI 


C X ( 1 ) . 










13 PET-AGE PI 

5 


C 99. 










DTR> READY PETS© 












DTR > PRINT FIRST 2 PETS© 












NUMBER 


KID 




KID 


PET 


PET 


FATHER MOTHER KIDS 


NAME 




AGE 


NAME 


AGE 


JIM LORAINE 2 


GARY 




24 


POP 


03 










SODA 


04 




SUE 




23 


MOUSE 


03 










SHORTY 


08 


JIM ANN 2 


URSULA 




7 


SOUEEKY 


03 










FRANK 


07 




RALPH 




3 




00 












00 
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5.4.4 Changing the Length of a List 



If you define a record-with the OCCURS clause, you can change the number of 
occurrences in a list. If you specify the MAX clause when denning the data file, 
all records have enough space for the maximum number of occurrences, and you 
can always change the number of occurrences up to the limit you have set: 



DTR > DEFINE FILE FOR FAMILIES MAX 



If you do not specify the MAX clause when you define a sequential file, 
DATATRIEVE sets the length of each record when you store it. In that case, you 
cannot add examples to the list. You can always decrease the number of occur- 
rences, though, and you can increase the number of occurrences back to the orig- 
inal number. 

If you do not specify the MAX clause and the file organization is indexed, you can 
still change the number of occurrences. 

The following example shows how to add items to a list. Because you are modify- 
ing an existing record, you use MODIFY rather than STORE to add items to the 
list: 



DTR > READY I NDEXED_F AM I L I ES WRITE© 
DTR > FIND FIRST 1 INDEX ED_FAMILI E S©) 
CI Record found! 
DTR > select; PRINT© 

NUMBER KID 
FATHER MOTHER KIDS NAME AGE 



JIM 



ANN 



URSULA 
RALPH 



DTR > MODIFY NUMBER_K IDS©) 
Enter NUMBER_K I DS : 4© 
DTR> FIND KIDS© 
[fl records found] 
DTR> SELECT 3© 
DTR > MODIFY© 
Enter K I D_NAME : NICKY© 
Enter AGE: 2© 
DTR > SELECT 4© 
DTR > MODIFY© 
Enter K I D_NAME : 
Enter AGE: 1© 
DTR > PRINT FIRST 



TAM© 

INDEX ED_FAMILIE S©) 



1 



FATHER 



MOTHER 



NUMBER 
KIDS 



KID 
NAME 



AGE 



JIM 



ANN 



DTR > 



URSULA 
RALPH 
NICKY 
TAM 



For information on retrieving data from hierarchical records, see Chapter 14 in 
this manual. 
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Defining Files 



The way you define a data file determines how much storage space the file occu- 
pies, how quickly you can retrieve data from the file, and whether you can 
change or duplicate data fields in that file. 

DATATRIEVE is based on RMS, the standard DIGITAL record and file manage- 
ment software facility. Based on how you define your data files, DATATRIEVE 
uses RMS to create, define, store, manipulate, and maintain information within 
your files. Your operating system documentation will give you more information 
on RMS. 

You can define two types of files in DATATRIEVE: 

• Sequential files, which store records in the order you enter them 

• Indexed files, which store records according to the order of a specified key field 

This chapter discusses the DEFINE FILE command, the choices you have when 
deciding whether to use sequential or indexed files, and other options available 
to you when you define a file in DATATRIEVE. 

6.1 Choosing a Sequential or an Indexed File 

Sequential files require less storage space than indexed files but it often takes 
longer to retrieve data from sequential files. 

To retrieve records from a sequential file, DATATRIEVE searches records one by 
one according to their order in the file. To retrieve records from an indexed file, 
DATATRIEVE searches the file according to specified key fields. The key fields 
are searched first, regardless of their order in the data file. 
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Sequential organization is useful in certain applications. For example, if your 
records contain a date field and you frequently retrieve them in chronological 
order, it is often best to arrange the records in the order you stored them. You are 
likely to want sequential access to banking transactions, for example. 

Use sequential files for accessing large groups of records in the order you stored 
them. 

In other cases, sequential organization may be unnecessarily slow. When you 
use a record selection expression (RSE) to form a record stream or collection of 
records from a sequential file, DATATRIEVE has to start at the beginning of the 
file and read every record until it finds the ones that you request. 

If you use an RSE to form a record stream based on key fields, RMS searches 
through the index it maintains without having to read every record. If you need 
to access a small number of records distributed throughout a file, use an indexed 
file. 

6.1.1 Modifying and Deleting Records 

Because of differences in file organization, you modify and delete records differ- 
ently for sequential and indexed files. In a sequential file, you can use the 
MODIFY statement to change any field, but in an indexed file, you cannot mod- 
ify the primary key field. You also cannot modify secondary key fields defined 
with the NO CHANGE clause explained in the section on optional clauses later 
in this chapter. 

RMS does not allow you to use the ERASE statement in a sequential file where 
sequence is the basis of the file organization. If you need to erase records from 
your data file, use an indexed file. You can, however, use the MODIFY statement 
on records in sequential files and change every field to zero or spaces depending 
on the data type. 

6.1 .2 Summary of Differences 

Table 6-1 summarizes the differences between sequential and indexed files. 



Table 6-1 : A Comparison of Sequential and Indexed Files 



SEQUENTIAL FILE 


INDEXED FILE 


Stores records in the order you create them 

Takes up less storage space than an indexed 
file 

Allows you to modify any field 

Requires you to use MODIFY instead of 
ERASE 


Stores records according to the values in the 
primary key field 

Allows you to retrieve certain data faster 
than a sequential file does 

Does not allow you to modify primary key 
field or any key field that has NO CHANGE 
attribute 

Lets you use ERASE statement 
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Defining a File Using the DEFINE FILE Command 



DATATRIEVE can store and retrieve data using existing RMS data files, so it is 
compatible with other languages or utilities that use RMS. It can also create 
RMS files, including sequential files and multikey indexed files. The DEFINE 
FILE command forms an RMS data file for the domain you specify. It uses the 
format: 

DEFINE FILE [FOR] domain-name [,] 
"ALLOCATION = n 1 
SUPERCEDE [,...] 

[max J 

{ KEY = field-name-1 [([NO]CHANGE[,] [NO] DUP)] j [ ( ...] 

The DATATRIEVE-1 1 Reference Manual also discusses the DEFINE FILE 
command. 



6.2.1 Defining a Sequential File 

If you decide you want your data file to be sequential, follow these steps: 

1. Before you define a data file, the associated domain and record definitions 
must be in your dictionary. You can use the SHOW command to be sure that 
they are in place: 



DTR> SHOW YACHTS-SEQUENTIAL > YACHT® 
DOMAIN YACHTS-SEQUENTIAL 

USING YACHT ON YACHT. SEQ ! 
RECORD YACHT 
USING 
01 BOAT ♦ 
03 TYPE. 

OG MANUFACTURER PIC X<10) 
QUERY-NAME IS BUILDER. 
OS MODEL PIC X( 10) . 
03 SPECIFICATIONS 

QUERY-NAME SPECS. 
OS RIG PIC >((G) 

VALID IF RIG EQ "SLOOP" >" KETCH" »"MS" >"YAWL 
OB LENGTH_OVER_ALL PIC XXX 

VALID IF LOA BETWEEN 15 AND 50 
QUERY-NAME IS LOA, 
OB DISPLACEMENT PIC 33999 
QUERY-HEADER IS "WEIGHT" 
EDIT-STRING IS ZZ >ZZ9 
QUERY-NAME IS DISP. 
OB BEAM PIC 33. 
OG PRICE PIC 33333 

VALID IF PRICE>DISP*1 .3 OR PRICE EQ 
EDIT-STRING IS $$$»$$$, 

5 

DTR> 
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2. Use the DEFINE FILE command to define the file. For a sequential file, you 
need specify only the domain name in the DEFINE FILE command: 

DTR > DEFINE FILE FOR Y ACHTS_SEO(ret) 
DTR > 

3. Select the options you want to use with the file, as explained in the later sec- 
tion on optional clauses. 

6.2.2 Defining an Indexed File 

You use the KEY clause in the DEFINE FILE command to create an indexed file. 
The clause creates an indexed file and specifies a field in the record definition to 
be an index key for the domain's data file. The first key field you name in the 
DEFINE FILE command is the primary key. All subsequent keys are alternate 
keys. 

If you decide you want your file to be indexed, first analyze your record definition 
to decide which field or fields you want to be key fields. 

You can designate only one primary key field, but you can name as many 
alternate key fields as you wish from the remaining fields in the record. 
DATATRIEVE searches the primary and alternate fields independently, so defin- 
ing alternate keys does not slow performance for queries based on the primary 
key. 

To choose a primary key, decide which field of the record you are likely to name 
most often in queries. Make certain you will not want to change that field, 
because DATATRIEVE does not allow you to change the values in primary keys. 

Finally, look for a field that has a unique value for each record. Unless you spec- 
ify otherwise, DATATRIEVE does not allow you to have the same value in more 
than one primary key field. For instance, you could not have two records in 
PERSONNEL with the ID 99883. You can use the DUP option to allow dupli- 
cates, as explained later in this chapter, but duplicate values slow performance. 

If you were setting up a PERSONNEL domain, you might predict that most 
users seeking information on an employee would base their search on the ID. 
You would not want to change identification numbers, and no two employees 
should have the same identification number. Consequently, ID uniquely identi- 
fies a record and is a good primary key for your PERSONNEL domain. This 
DEFINE FILE command would make ID the primary key for the indexed file 
PERSONNEL: 

DTR > DEFINE FILE FDR PERSONNEL t KEY=ID(ret) 
DTR > 
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6.2.2.1 Using a Group Field as the Primary Key — If the field you use most often 
does not uniquely identify each record, you can find another field that, together 
with the first, does identify the record. Then designate a group field made up of 
the two fields as the primary key. In the domain YACHTS the elementary field 
MANUFACTURER does not uniquely identify a record. ALBIN, for instance, is 
the builder of three of the first five YACHTS: 



DTR> PRINT FIRST 5 YACHTS© 









LENGTH 














OVER 








ANUFACTURER 


MODEL 


RIG 


ALL 


WEIGHT 


BEAM 


PRICE 


ALBERG 


37 MK II 


KETCH 


37 


20 »000 


12 


$36 ,951 


ALBIN 


79 


SLOOP 


26 


4 »200 


10 


$17 ,900 


ALBIN 


BALLAD 


SLOOP 


30 


7 ,276 


10 


$27 #500 


ALBIN 


VEGA 


SLOOP 


27 


5 ,070 


OS 


$18 tBOO 


AMERICAN 


2B 


SLOOP 


26 


4 ,000 


08 


$9 #895 



DTR > 



The combination of MANUFACTURER and MODEL, however, is unique for 
each record. These two fields are defined as the group field TYPE in the YACHT 
record definition. Therefore, TYPE, which has no duplicate values, makes a suit- 
able primary key. 

Note that when you use a group field as a primary key, you cannot modify any of 
the elementary fields in the group. In addition, note that BUILDER has been 
defined as a query name for MANUFACTURER in the YACHT record definition. 
This means you can use the shorter name BUILDER in place of 
MANUFACTURER in queries. 

If a group field is the primary key, list the field most commonly used in queries as 
the first elementary field in the group field. The field MANUFACTURER 
(BUILDER) appears in queries more frequently than MODEL, for example. 

When a group field such as TYPE is defined as a key field, keyed access will work 
only for queries involving the group field itself or the first elementary field in the 
group. With TYPE as the key field, DATATRIEVE conducts an indexed search 
for TYPE or BUILDER but a sequential search for the second elementary field, 
MODEL. 

If you want DATATRIEVE to use the first elementary field in a group field as a 
key, you must define that first field as either PIC X or PIC 9 in the group field 
definition. When you ready the domain, DATATRIEVE uses the group field as 
the key. If the first elementary field is anything but a simple numeric or charac- 
ter string, it is not treated as a key when the domain is readied. 

6.2.2.2 Defining Alternate Keys — If there are additional fields that you often use 
in queries, you can define them as alternate keys. DATATRIEVE performs an 
indexed search when you refer to an alternate key in a query. 
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You could make LENGTH_OVER_ALL an alternate key for YACHTS. Use this 
form of the DEFINE FILE command: 



DTR> DEFINE FILE FOR YACHTS KEY = TYPE* KEY = LOA(ret) 
DTR > 

DATATRIEVE allows duplicate values for the alternate keys unless you specify 
otherwise with the NO DUP option explained in a later section on options. 

Chapter 17 in this manual tells how to use key fields for optimum processing. 

6.2.2.3 Summary of Rules for Defining Key Fields — To set up key fields that 
DATATRIEVE can process most efficiently, use these guidelines: 

• When defining data, make the field most commonly used in queries the pri- 
mary key. 

• If the most commonly used field does not uniquely identify a record, combine it 
with another field in a field group so that the group field identifies the record. 

• Avoid duplicate values of a primary key when possible because duplications 
slow performance. 

• If you decide to make a group field the primary key, list the field most com- 
monly used in queries as the first elementary field. 

• If your record has other fields you often use with the primary key in queries, 
designate them as alternate keys. 

6.2.3 Optional Clauses with the DEFINE FILE Command 

You can use the following options in your DEFINE FILE command for both 
sequential and indexed files: 

• ALLOCATION = n 

ALLOCATION in the DEFINE FILE command refers to the allocation of disk 
blocks to a file. If you do not specify an allocation for a sequential file that you 
create, DATATRIEVE allots zero blocks to the file and then assigns space as 
needed. For an indexed file, it allots a small space when you create the file and 
additional space as needed. 

If you know your file is going to be large, however, you can use the 
ALLOCATION = n clause to reserve storage space for the file and increase the 
speed at which you can store records: 

DTR > DEFINE FILE FOR YACHTS ALLOCATION = 2000(reD 
DTR > 

See Chapter 17 for a discussion of techniques for optimizing response time and 
workspace. 



6-6 Defining Files 



• SUPERSEDE 



If you specify SUPERSEDE in your DEFINE FILE command, DATATRIEVE 
deletes the existing file with the same name and replaces it with the new one. 

Because RSTS/E systems keep only one version of a file, you must specify 
SUPERSEDE on RSTS/E systems when defining a file to replace one that 
already exists. If you do not, DATATRIEVE sends you an error message and 
does not create the new file: 

DTR > DEFINE FILE FOR YACHTS© 
File " YACHT . DAT " already exists 
DTR > 

On RSX systems, be sure that the complete file specification, including version 
number, duplicates the one you want to replace. Otherwise, DATATRIEVE 
keeps both the old and the new files. If the file you want to replace is 
YACHT.DAT;1, you would specify the replacement file as follows: 

DTR > DEFINE DOMAIN YACHTS USING YACHT ON YACHT • DAT 5 1© 
DTR > DEFINE FILE FOR YACHTS SUPERSEDE® 
DTR > 

• MAX 

As explained in Chapter 5, a record defined with the OCCURS clause allows 
you to vary the number of occurrences in a list. 

For a record with an OCCURS clause, use the MAX clause when defining the 
file. This reserves space in every record for the maximum possible number of 
list items. The record for FAMILIES, for instance, has this OCCURS clause: 

03 KIDS OCCURS TO 10 TIMES DEPENDING ON NUMBER-K IDS. 

If you request the MAX option when defining a file for FAMILIES, you reserve 
space for 10 kids in each record. Use this form of the command: 

DTR > DEFINE FILE FOR FAMILIES MAX@et) 
DTR > 

If you do not specify the MAX clause when you define a sequential file, 
DATATRIEVE sets the length of each record when you store it. In that case, 
you cannot add additional elements to the list. You can decrease the number of 
occurrences and you can also increase the number of occurrences back to the 
original number. 

If you specify more than one option in the DEFINE FILE command, separate 
each from the next with a comma. You do not have to specify the options in any 
particular order. 

DTR > DEFINE FILE FOR FAMILIES SUPERSEDE* ALLOCATION = 2000 f MA /((ret) 
DTR > 
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You can use these optional clauses with indexed files: 



• CHANGE or NO CHANGE 

The CHANGE or NO CHANGE clause determines whether or not you can 
modify the contents of the key field associated with the clause. To specify the 
CHANGE or NO CHANGE option, put the clause in parentheses after the 
name of the key field: 

DTR> DEFINE FILE FDR YACHTS KEY = TYPE (NO CHANGE ) (ret) 
DTR > 

You cannot specify CHANGE for a primary key. CHANGE is in effect for alter- 
nate keys unless you specify otherwise. 

• DUPorNODUP 

The DUP or NO DUP clause determines whether or not you can assign the 
same value to the specified key field in more than one record. Can more than 
one YACHTS record, for instance, have the value ALBIN for the key field 
BUILDER? 

NO DUP is the default for primary keys. However, DATATRIEVE allows you 
to specify DUP for primary keys. You may slow performance in retrieving 
records if you do so, because DATATRIEVE performs an indexed search to find 
the primary key and then a sequential search through the duplicates when it 
finds them. 

For alternate keys you can, by default, use duplicate values. You can specify 
NO DUP if you like, but eliminating duplicates from an alternate key field 
can limit the number of records you can store successfully. If you assigned RIG 
as an alternate key and specified the NO DUP option, for instance, you 
could store only four records in YACHTS: one sloop, one ketch, one yawl, 
and one MS. 

If you do not want duplicates and you do not want the alternate key values to 
change, put both sets of keywords in parentheses and separate them with a 
comma: KEY = field-name (NO DUP, NO CHANGE). 

This example defines an indexed file for YACHTS. It uses the group field TYPE 
as the primary key with the DUP option in effect, and RIG as an alternate key 
with the NO CHANGE option in effect: 

DTR > DEFINE FILE FOR YACHTS KEY = TYPE (DUP) ,||t) 

DFN > KEY = RIG (NO CHANGE ) (ret) 

DTR> 
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Limiting Record Streams with Record 7 

Selection Expressions I 



You define and store data so you can retrieve information in whatever form is 
most useful. You may want to perform any of these activities: 

• Display a group of records (PRINT or REPORT statements) 

• Form a temporary collection of records (FIND statement) 

• Update a group of records (MODIFY statement) 

To carry out any of these tasks, you must identify a record stream, that is, a 
group of records from a domain or collection. You form record streams with 
DATATRIEVE by specifying a record selection expression (RSE). 

By including various clauses in the RSE, you can determine the content of the 
record stream in several ways: 

• By specifying the number of records in the record stream (FIRST n clause) 

• By limiting the record stream to records that meet a conditional test (WITH 
clause) 

• By sorting the records according to the values of one or more fields (SORTED 
BY clause) 

This chapter presents many examples to teach you how to use RSEs. The exam- 
ples use RSEs with the PRINT statement, but you may use them with FIND, 
REPORT, or other DATATRIEVE statements. 

In addition, see Chapter 14 for information about another form of RSE that lets 
you access list items from hierarchical records. 
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7.1 Accessing All the Records in a Domain 



If a domain does not contain many records, you may be satisfied to display all of 
the records. You form one type of PRINT statement by typing PRINT followed by 
an RSE; for example: 

DTR > READY YACHTSgg) 
DTR > PRINT YACHTS® 

LENGTH 









OVER 












MANUFACTURER 


MODEL 


RIG 


ALL 


WEIGHT 


BEAM 


PRICE 


ALBERG 


37 MK II 


KETCH 


37 


20 


♦ 


12 


$3G 


#951 


ALB I N 


79 


SLOOP 


2G 


4 


♦ 200 


10 


$17 


#900 


ALBIN 


BALLAD 


SLOOP 


30 


1 


#27S 


10 


$27 


#500 


ALBIN 


MEGA 


SLOOP 


27 


5 


#070 


08 


$18 


#B00 


AMERICAN 


2B 


SLOOP 


2G 


4 


#000 


08 


$3 


#895 


AMERICAN 


2B-MS 


MS 


2G 


5 


#500 


08 


$18 


#895 


BAYFIELD 


30/32 


SLOOP 


32 


9 


#500 


10 


$32 


#875 


BLOCK I. 


40 


SLOOP 


39 


18 


#500 


12 






BOMBAY 


CLIPPER 


SLOOP 


31 


9 


#400 


1 1 


$23 


#950 


BUCCANEER 


270 


SLOOP 


27 


5 


#000 


08 






BUCCANEER 


320 


SLOOP 


32 


12 


#500 


10 






C&:C 

« 


CORVETTE 
« 


SLOOP 

4 


31 
• 


8 


#G50 

♦ 


08 

4 




4 


« 

VENTURE 


• 

r ? r ? r ? 


« 

SLOOP 


4 
4 

22 




* 

#000 


4 

07 


$3 


4 

#5G4 


WESTERLY 


CENTAUR 


SLOOP 


2B 


B 


#700 


08 


$15 


#245 


WESTSAIL 


32 


SLOOP 


32 


19 


#500 


1 1 






WINDPOWER 


IMPULSE 


SLOOP 


IB 




B50 


07 


$3 


#500 


WRIGHT 


SEAWIND II 


SLOOP 


32 


14 


#900 


00 


$34 


#480 



DTR > 

The PRINT YACHTS statement gives a display of all the records in the YACHTS 
domain. The source for the RSE is YACHTS, the name of the domain. Each RSE 
must include a source for the records, either a domain name, collection name, or 
list name. 

For clarity, you may want to specify the keyword ALL when you want a record 
stream to include all the records in a domain. The keyword ALL is optional. For 
example, PRINT ALL YACHTS and PRINT YACHTS are equivalent. 
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Specifying the Number of Records in the Record Stream 



The keywords ALL and FIRST let you indicate the number of records in the 
record stream. To specify the number of records in the record stream, type FIRST 
followed by a number before typing the source for the RSE. For example: 

DTR > PRINT FIRST 5 YACHTS© 

LENGTH 
OVER 



MANUFACTURER 


MODEL 


RIG 


ALL 


WEIGHT 


BEAM 


PRICE 


ALBERG 


37 MK II 


KETCH 


37 


20 #000 


12 


$38 #951 


ALB I N 


79 


SLOOP 


2G 


a #200 


10 


$17 #900 


ALBIN 


BALLAD 


SLOOP 


30 


7 #27G 


10 


$27 #500 


ALB I N 


VEGA 


SLOOP 


27 


5 #070 


08 


$18 #600 


AMERICAN 


2B 


SLOOP 


2G 


a #000 


08 


$9 #895 



DTR > 



In this case FIRST 5 YACHTS is the RSE. DATATRIEVE displays the first five 
records in YACHTS according to their order in the data file. An RSE can have 
either form: 

FIRST n domain-name for a domain 

FIRST n collection-name •*- for a collection 

where n is any number less than or equal to the total number of records in the 
domain or collection. 

If n is greater than the number of records in the source, DATATRIEVE gives you 
all the records that fulfill the RSE and does not display a message on your 
terminal. 

Limiting the record stream can be useful when you are testing procedures, com- 
plex RSEs, or report specifications. You can conduct your tests without having to 
wait for DATATRIEVE to display the complete set of records. 

Specifying the number of records can be useful, too, when you want to display a 
fixed number of those records that meet the requirements of the RSE: 

DTR > PRINT FIRST 5 YACHTS WITH PRICE NE 0(H) 

LENGTH 









□ UER 








ANUFACTURER 


MODEL 


RIG 


ALL 


WEIGHT 


BEAM 


PRICE 


ALBERG 


37 MK II 


KETCH 


37 


20 #000 


12 


$38 #951 


ALBIN 


79 


SLOOP 


2B 


a #200 


10 


$17 #900 


ALBIN 


BALLAD 


SLOOP 


30 


7 #278 


10 


$27 #500 


ALBIN 


MEGA 


SLOOP 


27 


5 #070 


08 


$18 #800 


AMERICAN 


2B 


SLOOP 


28 


4 #000 


08 


$9 #895 



DTR> 
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Identifying Records with Conditional Expressions 



There are several ways to limit the number of records in the record stream. 
Often you are interested in grouping similar records together, regardless of their 
position in the domain or record stream. You can restrict the record stream to 
those records that satisfy a specified condition by using the WITH clause of the 
RSE. Different forms of the WITH clause specify different types of relationships 
between the values of the same field for different records. You can form record 
streams based on: 

• Patterns among the field values (EQUAL, NOT EQUAL, CONTAINING) 

• Field values that fall within a specified range (BETWEEN... AND..., LESS 
THAN, GREATER THAN) 

• Field values you can or cannot find in a table 

7.3.1 Comparing Records by Pattern Recognition 

You can group records if the characters of a field value are equal or not equal to a 
specified value; for example: 

DTR > PRINT YACHTS WITH 5UILDER = " ALB I N "(ret) 

LENGTH 
OVER 



MANUFACTURER 


MODEL 


RIG 


ALL 


WEIGHT 


BEAM 


PRICE 


AL6IN 


79 


SLOOP 


28 


a #200 


10 


$17 »800 


ALB I N 


BALLAD 


SLOOP 


30 


7 »27B 


10 


$27 #500 


ALBIN 


VEGA 


SLOOP 


27 


5 »070 


08 


$18 »B00 



DTR > 

This statement asks DATATRIEVE to examine each record of the YACHTS 
domain and display only those records with the value "ALBIN" for the 
BUILDER field. After testing each record of YACHTS, DATATRIEVE identifies 
and then displays each record that meets the specified condition. WITH 
BUILDER = "ALBIN" lets you limit the record stream to the records you wish 
to access. 

The expression, BUILDER = "ALBIN", is a Boolean expression. A Boolean 
expression controls a comparison between value expressions. A Boolean expres- 
sion is either true or false depending on the values of the field and the value 
expression specified. The term that relates the value expressions is called a 
relational operator. In this example the relational operator is the equal 
sign( = ). 

When you use EQUAL ( = ) or NOT EQUAL, you can list more than one value 
expression in the same Boolean expression. The following queries specify a group 
of value expressions for DATATRIEVE to compare with each field value. The 
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comma here is equivalent to saying AND BUILDER = , so that the statement 
tells DATATRIEVE to print all yachts by Albin and all yachts by Alberg: 



DTR > PRINT YACHTS WITH BUILDER = "ALBIN" t "ALBERG 









LENGTH 














OVER 








MANUFACTURER 


MODEL 


RIG 


ALL 


WEIGHT 


BEAM 


PRICE 


ALBIN 


73 


SLOOP 


2G 


4 »200 


10 


$17 ,300 


ALBIN 


BALLAD 


SLOOP 


30 


7 ,276 


10 


$27 >500 


ALBIN 


VEGA 


SLOOP 


27 


5 »070 


08 


$18 »S00 


ALBERG 


37 MK II 


KETCH 


37 


20 fOOO 


12 


$36 #951 


DTR > PRINT Y 


ACHTS WITH 


RIG NOT 


EQUAL ' 


■SLOOP" 


t "KETCH" 








LENGTH 














OVER 








MANUFACTURER 


MODEL 


RIG 


ALL 


WEIGHT 


BEAM 


PRICE 


AMERICAN 


2B-MS 


MS 


2G 


5 »500 


08 


$18 »835 


EASTWARD 


HO 


MS 


24 


7 »000 


03 


$15 ,300 


FJORD 


MS 33 


MS 


33 


14 »000 


1 1 




LINDSEY 


39 


MS 


33 


14 »500 


12 


$35 #300 


ROGGER FD 


M/S 


MS 


35 


17 tBOO 


1 1 





DTR > 



Note that the EQUAL ( = ) and NOT EQUAL operators are case sensitive. They 
see uppercase and lowercase letters as different: 

DTR > FIND YACHTS WITH BUILDER = " A 1 b i n " (ret) 
CO records found] 

DTR > FIND YACHTS WITH BUILDER = "ALBIN "(ret) 
C3 records found] 

Because the builders' names are in uppercase letters in the data file but lower- 
case letters in the first query, DATATRIEVE did not find any record for a builder 
named "Albin". However, for "ALBIN", it found three records. 

On the other hand, the CONTAINING operator is indifferent to the case of the 
letters. It finds matches if there is agreement with all of the letters in the field 
value or with a substring derived from the field value. Thus the CONT operator 
finds the "ALBIN" record if you specify either "Albin" or "bin", a three letter 
substring: 

DTR> FIND YACHTS WITH BUILDER CONT " A 1 b i n " (ret) 
C3 records found] 



DTR> PRINT Y 


ACHTS WITH 


BUILDER 


CONT " 


b i n 


"(RET) 














LENGTH 


















OVER 












MANUFACTURER 


MODEL 


RIG 


ALL 


WEIGHT 


BEAM 


PRICE 


ALBIN 


73 


SLOOP 


2B 


4 


>200 


10 


$17 


»900 


ALBIN 


BALLAD 


SLOOP 


30 


7 


»27B 


10 


$27 


»500 


ALBIN 


VEGA 


SLOOP 


27 


5 


♦ 070 


08 


$18 


>B00 



DTR > 

I 
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DATATRIEVE finds and displays each record that contains the substring "bin" 
in the value for BUILDER. 

Note that another difference between EQUALS and CONTAINING is that 
DATATRIEVE can optimize EQUALS if the field is an RMS key, but it cannot 
optimize for CONTAINING. The CONTAINING operator always reads every 
record in the file. The EQUALS operator does not have to read each record if the 
field is a key. 

7.3.2 Grouping Records When Values Fall Within a Range 

DATATRIEVE allows you to use a variety of relational operators to test whether 
a field value for a record falls within a specified range. These operators are 
GREATER_THAN (> or GT), GREATER-EQUAL (GE), LESS-THAN « or 
LT), LESS_EQUAL (LE), and BETWEEN (BT): 



DTR > PRINT Y 


ACHTS WITH 


PRICE 


GREATER. 


THAN SOOOOgET) 










LENGTH 














OVER 








MANUFACTURER 


MODEL 


RIG 


ALL 


WEIGHT 


BEAM 


PRICE 


CHALLENGER 


41 


KETCH 


41 


2G ,700 


13 


$51 ,228 


ISLANDER 


FREEPORT 


KETCH 


41 


22 ,000 


13 


$54 ,370 


OLYMPIC 


ADVENTURE 


KETCH 


42 


24 ,250 


13 


$80 ,500 


DTR > PRINT Y 


ACHTS WITH 


PRICE 


GREATER. 


EQUAL 5( 


:>ooo(re 


D 








LENGTH 














OVER 








MANUFACTURER 


MODEL 


RIG 


ALL 


WEIGHT 


BEAM 


PRICE 


CHALLENGER 


41 


KETCH 


41 


2G ,700 


13 


$51 ,228 


ISLANDER 


FREEPORT 


KETCH 


41 


22 ,000 


13 


$54 ,870 


NORTHERN 


37 


KETCH 


37 


14 ,000 


1 1 


$50 ,000 


OLYMPIC 


ADVENTURE 


KETCH 


42 


24 ,250 


13 


$80 ,500 



DTR > 



Note the difference between the two record streams. Northern, priced at exactly 
$50,000, appears when the Boolean expression is PRICE GREATER-EQUAL 
50000, but it does not appear when you use the GREATER-THAN operator. 

The LESS-THAN and LESS-EQUAL operators work in a similar manner. The 
LESS— EQUAL operator includes a record if its field is either less than or equal to 
the value expression specified. 

The BETWEEN operator is the equivalent of the GREATER-EQUAL and 
LESS_EQUAL operators combined. It searches for records with field values that 
are within the range specified or equal to either of the value expressions that 
determine the range. For the BETWEEN operator to work, the range must go 
from a smaller value to a larger one. In the following example, the Boolean 
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expression identifies a record stream that includes records with values for 
PRICE between $50,000 and $90,000: 

DTR > PRINT YACHTS WITH PRICE BETWEEN 50000 AND 90000(reT) 



LENGTH 
OVER 



MANUFACTURER 


MODEL 


RIG 


ALL 


WEIGHT 


BEAM 


PRICE 


CHALLENGER 


41 


KETCH 


41 


26 #700 


13 


$51 »228 


ISLANDER 


FREEPORT 


KETCH 


41 


22 »000 


13 


$54 ,970 


NORTHERN 


37 


KETCH 


37 


14 #000 


1 1 


$50 i000 


OLYMPIC 


ADVENTURE 


KETCH 


42 


24 >250 


13 


$80 #500 



DTR > 



7.3.3 Grouping Records by Reference to a Table 

Some domains are associated with dictionary tables containing code strings that 
correspond to values in a field in the record. You can form an RSE that causes 
DATATRIEVE to look up the field value in the table. You can use the relational 
operator IN to compare the contents of a field with the code strings in a diction- 
ary table or domain table. If there is a match on the code string in the table, 
DATATRIEVE includes the record in the record stream. Two queries using 
table-based RSEs are FIND YACHTS WITH RIG IN RIG_TABLE and FIND 
YACHTS WITH RIG NOT IN RIG_TABLE. 

See Chapter 12 for a discussion of tables. 

7.3.4 Summary of the Relational Operators 

Table 7—1 summarizes all of the relational operators available to form Boolean 
expressions in the WITH clause of an RSE. 



Table 7-1 : Conditional Comparisons for an RSE 



Type of 
Comparison 


Relationship of 
Values in Boolean 


Relational 
Operator 


Boolean Expression 


Pattern 
recognition 


Exact match (case 
sensitive) 


EQUAL 
EQ 


BUILDER = "ALBIN" 
"ALBIN" = BUILDER 




No match (case 
sensitive) 


NE 

NOT_EQUAL 
NOTEQUAL 


BUILDER NE "ALBIN" 
"ALBIN" NE BUILDER 




Substring matches 
(not case 
sensitive) 


CONT 

CONTAINING 


BUILDER CONT "bin" 




Substring does not 
match (not case 
sensitive) 


NOT CONT 

NOT CONTAINING 


BUILDER NOT CONT 
"bin" 



(continued on next page) 
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Table 7-1 : Conditional Comparisons for an RSE (Cont.) 



TypG of 
Comparison 


Relationship of 
Values in Boolean 


Relational 
Operator 


Boolean Expression 


Value within 
a range 


Value is 
greater than 


> 

GT 

GREATER_THAN 


PRICE > 50000 
50000 > PRICE 




Value is 

greater than or = 


GE 

GREATER_EQUAL 


PRICE GE 50000 
50000 GE PRICE 




Value is 
less than 


< 
LT 

LESS.THAN 


PRICE < 20000 
20000 < PRICE 




Value is 

less than or = 


LE 

LESS_EQUAL 


PRICE LE 20000 




Value is 

between the two 
values or = to one 


BT 

BETWEEN 


PRICE BETWEEN 
30000 AND 54000 


Look up in 
table 


Field value is in 
the table 


IN table-name 


RIG IN RIG_TABLE 




Field value is not 
in the table 


NOT IN table-name 


RIG NOT IN 
RIG_TABLE 


Record stream 
empty 


Record stream is 
not empty 


ANY rse 


FAMILIES WITH ANY 
KIDS 




Record stream is 
empty 


NOT ANY rse 


FAMILIES WITH NOT 
ANY KIDS 



7.3.5 Setting Up Multiple Tests with Compound Booleans 

Thus far, each Boolean expression imposed just one test for records to be included 
in the record stream. To set up multiple or complex tests for records, you can join 
two or more Boolean expressions together. Expressions that join Booleans are 
Boolean operators. 

There are four Boolean operators: AND, OR, NOT, and BUT. With AND, OR, and 
BUT you can join two or more Boolean expressions together to form a single 
Boolean expression. NOT allows you to reverse the value of a Boolean 
expression. 

If you link Boolean expressions with AND or BUT, the resulting Boolean expres- 
sion is true only if all the Booleans linked with AND or BUT are true. 

If you link Boolean expressions with OR, the resulting Boolean expression is 
true if any one of the Booleans linked with OR is true. 

If you precede a Boolean expression with NOT, the resulting Boolean expression 
is true if the Boolean expression following NOT is false. 
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The following example shows the use of the Boolean operator: 



>TR> PRINT Y 


ACHTS WITH 


RIG = MS 


OR LOA 


= 33(RET) 












LENGTH 














OVER 








IANUFACTURER 


MODEL 


RIG 


ALL 


WEIGHT 


BEAM 


PRICE 


AMERICAN 


2G-MS 


MS 


2B 


5 #500 


08 


$18 #835 


BLOCK I. 


40 


SLOOP 


33 


18 # 500 


12 




EASTWARD 


HO 


MS 


24 


7 #000 


03 


$15 #300 


FJORD 


MS 33 


MS 


33 


14 #000 


1 1 




LINDSEY 


33 


MS 


.33 


14 #500 


12 


$35 #300 


PEARSON 


39 


SLOOP 


33 


17 #000 


12 




ROGGER FD 


M/S 


MS 


35 


17 #800 


1 1 





DTR > 



The query displays data on all yachts that have a RIG that is MS or an LOA 
equal to 39. For DATATRIEVE to include a record in the record stream, it must 
find that the record from YACHTS satisfies either condition or both. 

Sorting the Record Stream by Field Values 

When you use a PRINT statement to display a record stream, the primary key 
defined for the data file determines the order of the records. However, you can 
use the SORTED BY clause of the RSE to sort the record stream in a different 
order. For example, the records in YACHTS are already sorted by BUILDER, the 
first part of the primary key (TYPE) for the data file. 

If you are interested in the length of the boats, you can sort the records by LOA. 
To break down each length yacht by weight, specify DISP, the query name for 
displacement, as an additional sort key. The following query first sorts the 
YACHTS records according to LOA and DISP, then limits the record stream to 
the first five records: 

DTR > FIND YACHTS SORTED BY LOA # DISP(reT) 

[113 records found] 

DTR> PRINT FIRST 5 CURRENT(ret) 

LENGTH 









OVER 








ANUFACTURER 


MODEL 


RIG 


ALL 


WEIGHT 


BEAM 


PRICE 


WINDPOWER 


IMPULSE 


SLOOP 


IB 


B50 


07 


$3 #500 


CAPE DORY 


TYPHOON 


SLOOP 


13 


1 #300 


OG 


$4 #235 


ENCHILADA 


20 


SLOOP 


20 


2 #300 


07 




SAN JUAN 


21 


SLOOP 


21 


1 #250 


07 




VENTURE 


21 


SLOOP 


21 


1 #500 


07 


$2 #823 



DTR > 
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The SORTED BY clause takes precedence over the original sort order for the 
record stream. It does not change the file organization of the records. The 
SORTED BY clause enables you to produce reports with data records organized 
into groups. Certain fields will control how the organization of these reports 
takes place. For more information on control group reports, see the 
DATATRIEVE-1 1 Guide to Writing Reports. 
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Using Compound Statements 



8 



When you want to do something in DATATRIE VE that involves definitions in a 
data dictionary, you usually need to use a DATATRIE VE command. When you 
want to manipulate data in a dictionary, you usually use DATATRIEVE state- 
ments, such as STORE, MODIFY, PRINT, and FIND. 

You can enter individual statements or combine them into compound state- 
ments. You can enter statements at DATATRIEVE command level (the DTR> 
prompt), in procedures, or in command files. 

You can also enter individual commands at DATATRIEVE command level, in 
procedures, or command files. However, you cannot combine DATATRIEVE com- 
mands into compound commands, mix commands and statements to form com- 
pound statements, or include commands in BEGIN-END blocks. 

Table 5-1 in the DATATRIEVE-1 1 Reference Manual tells you whether a 
DATATRIEVE keyword is used in commands or statements. 

This chapter describes the use of compound statements, REPEAT and FOR 
statements, and BEGIN-END blocks. 

8.1 Using REPEAT to Combine Statements 

Often you want to use the same DATATRIEVE statement over and over. For 
instance, if you are storing five new boats into the domain YACHTS, you could 
ready the domain for WRITE access and then repeat the instruction STORE 
YACHTS five times. 



8-1 



By using a compound statement, however, you can combine the STORE state- 
ment with a REPEAT statement and then type the STORE statement only once 
for the five records. The following example shows a frequent use of a compound 
statement - combining STORE with REPEAT: 

DTR > READY YACHTS WRITE© 

DTR > REPEAT 3 STORE YACHTS© 

Enter MANUFACTURER: HOB I E© 

Enter MODEL: CAT© 

Enter RIG: SLOOP© 

Enter LENGTH OVER ALL: 22(H) 

Enter DISPLACEMENT: 4000© 

Enter BEAM: 8© 

Enter PRICE: G500© 

Enter MANUFACTURER: R I DGE© 

Enter MODEL: ACT© 

Enter RIG: SLOOP© 

Enter LENGTH OYER ALL: 22© 

Enter DISPLACEMENT: 3500© 

Ente r BEAM -.(tab) © 

Enter PRICE: (tab) © 

Enter MANUFACTURER: ROBERTS© 

Enter MODEL: Zll© 

Enter RIG: SLOOP© 

Enter LENGTH OVER ALL: 25© 

Enter DISPLACEMENT: 4500© 

Enter BEAM: 10© 

Enter PRICE: 7500© 

DTR > 

Prompts are repeated for each field in the record until data is stored in the speci- 
fied number of records or until you end the operation by entering CTRL/Z. 

When you use a REPEAT statement with MODIFY, PRINT, and REPORT state- 
ments, you may also want to use a prompting value expression (*.prompt). You 
probably do not want to PRINT, MODIFY, or REPORT on a single record more 
than once. However, you can use a prompting value expression to supply new 
information each time a statement is repeated. 

The following example uses the prompting value expression with a REPEAT 
loop: 

DTR > SET NO PROMPT© 
DTR> READY YACHTS© 

DTR > REPEAT *♦ "NUMBER OF TIMES TO REPORT"© 
C0N> BEGIN© 

C0N> REPORT FIRST 1 YACHTS WITH LOA = *."THE LOA"© 
RW> PRINT BOAT© 
RW> END REPORT© 
C0N> END© 

Enter NUMBER OF TIMES TO REPORT: 2© 
Enter THE LOA: 37© 

(continued on next page) 
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23-0ct-87 
Pasf e 1 



MANUFACTURER MODEL RIG 

ALBERG 37 MK II KETCH 

Enter THE LOA : 3G© 



LENGTH 
OVER 
ALL 

37 



WEIGHT 
20 #000 



BEAM 
12 



PRICE 
$36 #951 



MANUFACTURER 
CABOT 



MODEL 



36 



RIG 
5L00P 



LENGTH 
OVER 
ALL 

36 



WEIGHT 
15 #000 



BEAM 



12 



23-0ct-87 
PaSe 1 



PRICE 



DTR > 



A compound statement can include any DATATRIEVE statement except FIND, 
SELECT, DROP, RELEASE, or SORT. 

Note that if you follow the REPEAT statement with a procedure, DATATRIEVE 
repeats only the first statement in the procedure. To repeat the complete proce- 
dure, you must use a BEGIN-END block, described in a later section in this 
chapter. Note also that a procedure in a REPEAT statement cannot include 
DATATRIEVE commands. 



8.2 Using the FOR Statement 

You can use a FOR statement when you want to access individual fields more 
than once. Suppose you want to supply a price for yachts with no price listed. You 
do not want to change all the fields in the target records. You want to change 
only the price field for specific yachts. First, form a collection of the boats you 
want to modify. Then, use a FOR statement to modify the target records: 



DTR > SET NO PROMPT© 

DTR> READY YACHTS MODIFY© 

DTR > FIND FIRST 3 YACHTS WITH PRICE = 0© 
C 3 records found] 
DTR > PRINT ALL® 



LENGTH 
OVER 

MANUFACTURER MODEL RIG ALL WEIGHT BEAM PRICE 



BLOCK I. 40 SLOOP 

BUCCANEER 270 SLOOP 
BUCCANEER 320 SLOOP 

DTR > FOR CURRENT© 
C0N> MODIFY USING PRICE = DISP * 1.3 + 5000© 
DTR > PRINT CURRENT© 

(continued on next page) 



39 18*500 12 

27 5 #000 08 

32 12 #500 10 
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LENGTH 














OVER 








MANUFACTURER 


MODEL 


RIG 


ALL 


WEIGHT 


BEAM 


PRICE 


BLOCK I* 


40 


SLOOP 


39 


1 8 #500 


12 


$29 #050 


BUCCANEER 


270 


SLOOP 


27 


5 #000 


08 


$11 #500 


BUCCANEER 


320 


SLOOP 


32 


12 #500 


10 


$21 #250 



DTR > 



8.3 Using BEGIN-END Blocks to Combine Statements 

Another way to combine statements is the BEGIN-END block, which causes 
DATATRIEVE to treat several statements as one statement. BEGIN-END 
blocks are especially useful within FOR, STORE, and REPEAT statements. 

8.3.1 BEGIN-END Blocks in FOR Statements 

You can, for instance, use a BEGIN-END block in a FOR statement to modify the 
price field in specific records. The BEGIN-END block lets you include two PRINT 
statements within the MODIFY statement — the first to display the unchanged 
records, the second to show the records after DATATRIEVE has modified them: 

DTR> SET NO PROMPT® 

DTR > READY YACHTS WRITE© 

DTR > FOR YACHTS WITH PRICE = 0© 

C0N> MODIFY USING© 

C0N> BEGIN© 

C0N> PRINT© 

C0N> PRICE = *,"NEW PRICE"© 
C0N> PRINT© 
C0N> END© 

LENGTH 
OVER 



MANUFACTURER MODEL 


RIG 


ALL 


WEIGHT 


BEAM 


PRICE 


BLOCK I, 40 


SLOOP 


39 


1 8 »500 


12 




Enter NEW PRICE: 29050© 














LENGTH 












OVER 








MANUFACTURER MODEL 


RIG 


ALL 


WEIGHT 


BEAM 


PRICE 


BLOCK I , 40 


SLOOP 


39 


18 >500 


12 


$29 »050 


BUCCANEER 270 


SLOOP 


27 


5 tOOO 


08 





Enter NEW PRICE: "2 

Execution terminated bv operator 

DTR > 



8-4 Using Compound Statements 



8.3.2 IF-THEN-ELSE Statements in BEGIN-END Blocks 



You can include an IF-THEN-ELSE statement with a prompting expression 
within the block to allow you to decide whether or not to modify each record 
stream: 



DTR> SET NO PROMPT© 

DTR > FOR FIRST 3 YACHTS WITH PRICE = 0© 
C0N> BEGIN© 

C0N> IF *."Y TO MODIFY PRICE* N TO SKIP" CONT "Y"© 

C0N> THEN MODIFY PRICE ELSE© 
CON> PRINT "NO CHANGE "(ret) 
CON> END© 

Enter Y TO MODIFY PRICE* N TO SKIP: Y © 
Enter PRICE: 23456 © 

Enter Y TO MODIFY PRICE* N TO SKIP: N © 
NO CHANGE 

Enter Y TO MODIFY PRICE* N TO SKIP: N © 
NO CHANGE 

DTR> 

Conversely, if there are several DATATRIE VE statements required in the THEN 
and ELSE clauses, include them in BEGIN-END blocks. 

8.3.3 Using BEGIN-END Blocks in STORE Statements 

Often you may want to include a number of lines in the BEGIN-END block. The 
following example shows how to use: 

• A BEGIN-END block within the STORE statement 

• A prompting value expression to request user response 

• A BEGIN-END block in a VERIFY clause 

• A VERIFY clause with a USING clause to allow you to decide whether or not 
to store the record displayed in the PRINT statement 

• A context variable (A) to establish DATATRIE VE context 



See Appendix A for more information on DATATRIE VE context. 



DTR> READY YACHTS WRITE© 

DTR > STORE A IN YACHTS USING© 

CON> BEGIN© 

C0N> BUILDER = *,BUILDER© 

CON> MODEL = *♦ MODEL© 

CON> RIG = *,RIG© 

CON> LOA = *, LENGTH© 

CON> DISP = *. WEIGHT© 

CON> BEAM = * . BEAM© 

C0N> PRICE = DISP * 1.3 + BEAM * 100© 

C0N> END VERIFY USING© 

C0N> BEGIN© 

C0N> PRINT A, BOAT, SKIP© 

C0N> IF *♦ CONFIRMATION CONT "N" THEN© 

C0N> ABORT "BAD RECORD"© 

'C0N> END© 
DTR > 
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When you press RETURN to enter the compound statement, DATATRIEVE 
prompts for each of the fields in the YACHT record, then requests a confirmation: 

Enter BUILDER: CRIS-CRAFT© 
Enter MODEL: (tab) (ret) 
Enter RIG: KETCH© 
Enter LENGTH: 32© 
Enter WEIGHT: 8 »725© 
Enter BEAM: 10© 

LENGTH 
OUER 

MANUFACTURER MODEL RIG ALL WEIGHT BEAM PRICE MANUFACTURER 

CRIS-CRAFT KETCH 32 8 ,725 10 $12>343 CRIS-CRAFT 

Enter CONFIRMATION: N© 
ABORT: BAD RECORD 

DTR > FIND YACHTS WITH BUILDER = CR I S-CRAFT© 
CO records found] 



8.3.4 BEGIN-END Blocks in REPEAT Statements 

If you want to repeat a sequence of statements, use a BEGIN-END block inside a 
REPEAT statement. Suppose you wanted to store 50 new yachts using the 
MANUFACTURER, LOA, DISPLACEMENT, and PRICE fields. You could use 
the following BEGIN-END block to repeat the sequence of prompting 
statements: 



DTR > SET NO PROMPT© 

DTR > READY YACHTS WRITE© 

DTR > REPEAT 50 STORE YACHTS USING© 

C0N> BEGIN© 

C0N> MANUFACTURER = *. MANUFACTURER© 

C0N> LOA = *.L0A© 

C0N> DISPLACEMENT = * , D I SPLACEMENT© 

C0N> PRICE = *. PRICE© 

C0N> END© 

Enter MANUFACTURER: GRAMPIAN© 

Enter LOA: 40© 

Enter DISPLACEMENT: 1400© 

Enter PRICE: 23456© 

Enter MANUFACTURER: HIGGINS© 

Enter LOA: 37© 

Enter DISPLACEMENT: 1375© 

Enter PRICE: 147(35© 



DTR > 

For information on invoking a procedure in a REPEAT statement, see Chapter 9. 

Because statements that use BEGIN-END blocks can be quite long, it is often 
useful to put them into DATATRIEVE procedures so that you can edit and reuse 
them without having to retype them. The next chapter explains how to use 
procedures. 
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Using DATATRIEVE Procedures 



Often you want to execute the same series of commands and statements over and 
over again, and you may want to have other users execute those same commands 
and statements. Unless you use procedures, you have to retype the input each 
time. By using procedures, however, you can develop the series of steps once and 
then simply invoke the procedure each time you want to do the same steps over 
again. 

A procedure is a fixed sequence of DATATRIEVE commands and statements you 
create, name, and store in your data dictionary. A procedure can also contain 
portions of a command or statement, such as a complex value expression. 

9.1 Defining a Procedure 

For almost any series of statements you use over and over again, you can save 
yourself time by defining a single procedure. For example, you repeatedly per- 
form a simple query to display information about the manufacturers of large 
yachts: 

DTR > READY YACHTS© 

DTR > FIND BIGGIES IN YACHTS WITH LQA GT 40 SORTED BY BUILDER© 
C 8 records found] 
DTR > PRINT ALL© 

(continued on next page) 
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LENGTH 









OVER 








MANUFACTURER 


MODEL 


RIG 


ALL 


WEIGHT 


BEAM 


PRICE 


CHALLENGER 


41 


KETCH 


4 1 


2B »700 


1 3 


$51 >228 


COLUMBIA 


41 


SLOOP 


41 


20 »700 


1 1 


$48 ,490 


GULFSTAR 


41 


KETCH 


41 


22 fOOO 


12 


$41 f 350 


ISLANDER 


FREEPORT 


KETCH 


41 


22 >000 


13 


$54 ,970 


NAUTOR 


SWAN 41 


SLOOP 


41 


17 »750 


12 




NEWPORT 


41 S 


SLOOP 


41 


1 8 »000 


1 1 




OLYMPIC 


ADVENTURE 


KETCH 


42 


24 »250 


13 


$80 » 500 


PEARSON 


419 


KETCH 


42 


21 »000 


13 





DTR > 



Rather than type this query repeatedly, you can put it into a procedure. To define 
a procedure, enter the DEFINE PROCEDURE command at DATATRIEVE com- 
mand level. After typing the keywords DEFINE PROCEDURE, enter a name for 
the procedure and press RETURN. 

DTR > DEFINE PROCEDURE BUI LDERS(ret) 

DATATRIEVE then prompts with DFN> to indicate that it expects a procedure 
definition. Enter the commands or statements that form the procedure defini- 
tion. DATATRIEVE continues to prompt with DFN> until you enter the 
keyword END_PROCEDURE on a line by itself. 

DTR> DEFINE PROCEDURE BUILDERS© 
DFN > 
DFN > 
DFN > 

DFN > END-PROCEDURE© 
DTR> 

As soon as you enter END-PROCEDURE, DATATRIEVE stores the procedure 
definition in your current dictionary. It checks the syntax of the DEFINE 
PROCEDURE statement, not that of the statements the procedure contains. 
DATATRIEVE checks for syntax errors in those statements only when you 
invoke the procedure. 

Invoking a Procedure 

You invoke a procedure by preceding its name with a colon: 
:procedure-name 

The content of a procedure determines where you can invoke it. In general, you 
can invoke a procedure anywhere you can use the commands or statements con- 
tained in the procedure. For example, if the procedure contains only complete 
DATATRIEVE commands and statements, you can invoke it at the 
DATATRIEVE command level. 

DTR > :BUILDERS(reD 

Note that you cannot invoke a procedure during an ADT, EDIT, or GUIDE mode 
session or in a domain, record, or table definition. 
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In addition, when DATATRIEVE executes a procedure, you do not see the com- 
mands and statements in the procedure or the system messages that are nor- 
mally displayed. You see only the output that follows the last statement or 
command in the procedure. In the following example, the only output is in 
response to FIND YACHTS SORTED BY DESC PRICE, the last statement in 
the procedure EXPENSIVE: 

DTR > SHOW EXPENSIVE® 
PROCEDURE EXPENSIVE 
READY YACHTS 

FIND YACHTS SORTED BY DESC PRICE 

END-PROCEDURE 

DTR > : EX PENSIVE© 

C 1 1 3 records found] 

DTR > 

If you follow the FIND statement with another statement, you no longer receive 
the message about the number of records found: 



DTR > SHOW EXPENSIVE© 
PROCEDURE EXPENSIVE 
READY YACHTS 

FIND YACHTS SORTED BY DESC PRICE 

PRINT FIRST 5 CURRENT 

END-PROCEDURE 

DTR > : EXPENSIVE© 

LENGTH 









OVER 








MANUFACTURER 


MODEL 


RIG 


ALL 


WEIGHT 


BEAM 


PRICE 


OLYMPIC 


ADVENTURE 


KETCH 


42 


24 >250 


13 


$80 »500 


ISLANDER 


FREEPORT 


KETCH 


41 


22 >000 


13 


$54 f970 


CHALLENGER 


41 


KETCH 


41 


2G »700 


13 


$51 ,228 


NORTHERN 


37 


KETCH 


37 


14 tOOO 


1 1 


$50 »000 


COLUMBIA 


41 


SLOOP 


41 


20 f 7 


1 1 


$48 ,490 



DTR > 



Contents of a Procedure 

A procedure can contain any number of the following DATATRIEVE elements: 

• Full DATATRIEVE commands and statements 

• Command and statement clauses and arguments 

• Comments 
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9.3.1 Commands and Statements in Procedures 



You might define a procedure containing complete DATATRIE VE commands 
and statements. This one, for instance, finds and displays the biggest yachts in 
the domain: 



DTR > DEFINE PROCEDURE BIG-YACHTS© 

DFN > FIND BIGGIES IN YACHTS WITH LOA GT 40 SORTED BY BUILDER© 
DFN > PRINT ALL© 
DFN> END- PROCEDURE©) 
DTR > 

When you execute the procedure BIG_ YACHTS, the results are the same as 
entering the FIND and PRINT statements at the DATATRIEVE command level, 
indicated by the DTR> prompt: 

DTR > READY YACHTS© 
DTR > : BIG-YACHTS© 

LENGTH 
OYER 



IANUFACTURER 


MODEL 


RIG 


ALL 


WEIGHT 


BEAM 


PRICE 


CHALLENGER 


41 


KETCH 


41 


26 »700 


13 


$51 ,228 


COLUMBIA 


41 


SLOOP 


41 


20 >700 


1 1 


$48 #490 


GULFSTAR 


41 


KETCH 


41 


22 »000 


12 


$41 ,350 


ISLANDER 


FREEPORT 


KETCH 


41 


22 »000 


13 


$54 ,970 


NAUTOR 


SWAN 41 


SLOOP 


41 


17 ,750 


12 




NEWPORT 


41 S 


SLOOP 


41 


1 8 »000 


1 1 




OLYMPIC 


ADVENTURE 


KETCH 


42 


24 »250 


13 


$80 >500 


PEARSON 


419 


KETCH 


42 


21 »000 


13 





DTR > 



9.3.2 Arguments and Clauses 

Besides full commands and statements, a procedure can contain fragments of 
statements or commands. It can contain an argument or clause from a command 
or statement. For example, a procedure can contain a record selection 
expression: 

DTR > DEFINE PROCEDURE B I G_YACHTS_RSE© 

DFN > BIGGIES IN YACHTS WITH LOA GT 40 SORTED BY BUILDER© 
DFN > END_ PROCEDURE© 
DTR > 

Having separated the record selection expression from the FIND statement, you 
can use the procedure name as the argument of a FIND statement: 

DTR > FIND :BIG_YACHTS_RSE© 
C 8 records found] 
DTR > 
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In fact, you can use this procedure in any command or statement containing an 
RSE argument, such as the PRINT statement: 



DTR > PRINT ALL : B I G_YACHTS_RSE(ret) 



MANUFACTURER 



MODEL 



RIG 



LENGTH 
OVER 
ALL 



WEIGHT BEAM 



PRICE 



CHALLENGER 



41 
41 
41 



KETCH 
SLOOP 
KETCH 
KETCH 
SLOOP 
SLOOP 
KETCH 
KETCH 



41 
41 
41 
41 
41 
41 
42 
42 



2B 
20 



7 
700 


750 

250 




13 
1 1 
12 
13 
12 
1 1 
13 
13 



$51 ,228 
$48 ,490 
$41 ,350 
$54 ,970 



COLUMBIA 

GULFSTAR 

ISLANDER 

NAUTOR 

NEWPORT 

OLYMPIC 

PEARSON 



FREEPORT 
SWAN 41 
41 S 

ADVENTURE 
419 



17 
18 
24 
21 



$80 >500 



You can begin a procedure with the end fragment of a command or statement 
and include other whole commands or statements. You can also end a procedure 
with the beginning fragment of a command or statement after a series of com- 
plete commands and statements. 

9.3.3 Comments in Procedures 

A comment contains explanatory information for you or other users that 
DATATRIEVE does not interpret as input. To put a comment in a procedure, put 
an exclamation point (!) before the information that you want to include. 

When you invoke a procedure, DATATRIEVE processes it without displaying 
the contents of the procedure. To display the comments, use the SHOW command 
with the procedure name. You could, for instance, put a comment into the proce- 
dure BIG_ YACHTS-QUERY. The results of the procedure are the same as with- 
out the comment. But when you use a SHOW command, you can see the 
explanatory comment: 

DTR > SHOW BIG_ YACHTS-QUERY 
SET ABORT 

DECLARE LENGTH PIC 99 
VALID IF LENGTH GT 35, 

!THIS PROCEDURE SHOWS YACHTS GE SPECIFIED LENGTH 

LENGTH = *."MIN LOA " 
IF LENGTH GT 42 

THEN ABORT "NO BOATS THAT BIG" 

FIND BIGGIES IN YACHTS WITH LOA GE LENGTH SORTED BY BUILDER 
PRINT BUILDER, RIG, LOA, PRICE OF BIGGIES 
END-PROCEDURE 
DTR > 
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9.4 Using Procedures to Locate Errors 



When you invoke a procedure, DATATRIEVE processes the contents of the pro- 
cedure. If it finds an error, it issues a message. Suppose, for instance, you created 
the following long procedure: 

DTR> DEFINE PROCEDURE WAGE-REPORT 
DFN > REPORT NAGES 

DFN> SET REPORT-NAME = NEEKLY WAGE REPORT 
DFN > SET COLUMNS_PAGE = 70 
DFN> PRINT LAST-NAME > GROSS-PAY* FICA, 
DFN > FEDERAL-TAX t STATE-TAX » 

DFN > GR0SS_PAY - (FICA + FEDERAL-TAX + STATE-TAX ) * ( " NET PAY") USING 
DFN > $$,$$$, 39 

DFN > AT BOTTOM OF REPORT PRINT SKIP 2, COL 1» "TOTAL : " » 

DFN > TOTAL GROSS-PAY USING $$$,$$$. 99 » 

DFN > TOTAL FICA USING $$$,$$$, 99, 

DFN > TOTAL FEDERAL-TAX USING $$$»$$$»99> 

DFN > TOTAL STATE-TAX USING $$$»$$$. 99 » 

DFN > TOTAL (GROSS-PAY - (FICA + FEDERAL-TAX + STATE_TAX) ) USING 

$$$ ,$$$ , 99 

DFN > END-REPORT 

DFN > END-PROCEDURE 

DTR > 

If you have made any errors, DATATRIEVE stops executing when it finds the 
first error and sends you an error message, as in this example: 

DTR > : WAGE-REPORT© 

Invalid column header or report name (WEEKLY) 
DTR> EDIT WAGE-RE PORT© 

Edit the procedure to place quotation marks around "WEEKLY WAGE 
REPORT". Then try the procedure again: 

DTR > : WAGE-REPORT© 

Field "WAGES" is undefined or used out of context 
DTR > EDIT WAGE-REPORT©) 

To correct this second error, edit the procedure to place the READY WAGES com- 
mand before the REPORT statement-. Then invoke the procedure again: 

DTR > : WAGE-REPORT© 

Enter COLUMNS PER PAGE: 80© 

(continued on next page) 
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WEEKLY WAGE REPORT 



23-0ct-87 
Paae 1 



LAST 
NAME 



BLAKE 

DUNN 

HILL 

CHONTI 

MOONY 

STARK 



GROSS 
PAY 

$ 1 # . 
$1 »500 . 00 
$ 5 . 
$993,99 
$1 #900*98 
$ 9 * 5 ♦ 



FICA 

$103.86 
$145.87 
$52.93 
$103.85 
$145.87 
$145.87 



FEDERAL 
TAX 

$204.77 
$297.98 
$79.75 
$204.78 
$375.98 
$999.84 



STATE 
TAX 

$.01 
$54.32 
$32.98 
$57.90 
$75.90 
$108 . 90 



NET PAY 

$891 .38 
$1 #001 . 83 
$334.34 
$833.48 
$1 #303,23 
$8 #247.39 



TOTAL: 
DTR > 



$15 #400.97 



$898.25 



$2 #183.08 



$328.01 



$12 #211 .83 



9.5 A Sample Procedure 



You can create your own procedures now using the example in Figure 9-1 as a 
model. The following is a procedure that uses the Report Writer to write a sum- 
mary report of yacht data: 

DTR > DEFINE PROCEDURE YACHT_SUMMAR Y© 
DFN > SET ABORT© 

DFN > PRINT "THIS REPORT REQUIRES AN ESTABLISHED COLLECTION*"© 

DFN > PRINT "SORTED BY LOA AND BEAM . "(ret) 

DFN > PRINT "HAVE YOU ESTABLISHED A COLLECTION? "(ret) 

DFN > IF *."YES OR NO" CONTAINING "N" THEN ABORT "COLLECTION NEEDED 
DFN > REPORT ON *. "OUTPUT DEVICE OR FILE "(ret) 

DFN > SET REPORT_NAME = "EXAMPLE: REPORT FROM A PROCEDURE "(ret) 
DFN > SET LINES_PAGE = 55 # COLUMNS_PAGE = GO© 
DFN > PRINT BUILDER # MODEL* LOA » BEAM # PRICE© 

DFN > AT BOTTOM OF LOA PRINT SKIP# COL 30 "AVERAGE PRICE = " »© 
DFN > AVERAGE (PRICE)* SKIP© 

DFN > AT BOTTOM OF REPORT PRINT COL 17#"NUMBER OF BOATS = " #© 
DFN > COL 35 # COUNT* SKIP* "AVERAGE PRICE OF ALL BOATS = " *© 
DFN > AVERAGE (PRICE)© 
DFN > END_REPORT© 
DFN > END_ PROCEDURE©) 
DTR > 

Figure 9-1 : Sample Procedure 



This example illustrates some statements that are particularly useful in 
procedures: 

• Use the PRINT statement to display a message when the procedure is invoked. 

• The prompting value expression *."YES OR NO" requires a response to the 
question: HAVE YOU ESTABLISHED A COLLECTION? The Boolean expres- 
sion CONTAINING checks the user's response to the question. If the response 
is N or NO, the procedure aborts. 
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DTR > : YACHT_SUMMARY® 

THIS REPORT REQUIRES AN ESTABLISHED COLLECTION* 

SORTED BY LOA AND BEAM. 

HAVE YOU ESTABLISHED A COLLECTION? 

Enter YES OR NO: NQ(ret) 

ABORT: COLLECTION NEEDED 

DTR > 

• If you answer YES to the first prompt, but you do not actually have a current 
collection, the Report Writer aborts the procedure and prints an error message: 



DTR > : YACHT_SUMMARY(ret) 

THIS REPORT REQUIRES AN ESTABLISHED COLLECTION* 

SORTED BY LOA AND BEAM. 

HAVE YOU ESTABLISHED A COLLECTION? 

Enter YES OR NO: YES(ret) 

A current collection has not been established. 
DTR > 

• The prompting value expression *."OUTPUT DEVICE OR FILE" allows you to 
select the device or file to contain the report when DATATRIEVE executes the 
procedure. 

• If you make a collection of YACHTS with LOA between (and including) 36 and 
37 and price not equal to zero, DATATRIEVE displays the following report on 
your terminal: 



DTR > READY YACHTS© 

DTR > FIND YACHTS WITH LOA BETWEEN 3B 37 AND PRICE NE 0(ret) 
[5 records found] 

DTR > SORT CURRENT BY LOA t BEAM© 
DTR> :YACHT_SUMMAR Y(ret) 

THIS REPORT REQUIRES AN ESTABLISHED COLLECTION* 

SORTED BY LOA AND BEAM. 

HAVE YOU ESTABLISHED A COLLECTION? 

Enter YES OR NO: YES(ret) 

Enter OUTPUT DEVICE OR FILE: TI:(ret) 



EXAMPLE: REPORT FROM A PROCEDURE 



Ol-Apr-1987 
PajJe 1 



MANUFACTURER 



MODEL 



LENGTH 
OVER 
ALL 



BEAM 



PRICE 



ISLANDER 
I. TRADER 



3G 
37 



3B 
3B 



11 
12 



$31 »730 
$39 »500 



AVERAGE PRICE = 



$35 »G15 



IRWIN 

NORTHERN 

ALBERG 



37 MARK II 
37 

37 MK II 



37 
37 
37 



1 1 
1 1 
12 



$3B »950 
$50 »000 
$3B #951 



(continued on next page) 
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AVERAGE PRICE = 



$41 »300 



NUMBER OF BOATS = 5 
AVERAGE PRICE OF ALL BOATS = 



$39 »02B 



Nesting Procedures 

A nested procedure is a procedure within another procedure. 

The following procedure calculates the price per pound of a boat and assigns a 
column header and edit string for that value expression: 

DTR > DEFINE PROCEDURE PR I CE_PER_POUND(ret) 

DFN > PRICE/DISPLACEMENT ( " PR I CE " / " PER " / " POUND " > USING $$9.99(rIt) 
DFN> END_PROCEDURE(ret) 
DTR > 

You cannot invoke this procedure by itself, but you can invoke the 
PRICE_PER_POUND procedure in another procedure that prints the builder, 
model, and price per pound of all boats in the CURRENT collection, as follows: 

DTR > DEFINE PROCEDURE PR I CE_RE PORT(ret) 

DFN > PRINT ALL BUILDER* MODEL t : PR ICE_PER_POUND(RET) 

DFN > END_PROCEDURE(ret) 

DTR > 

When you invoke the procedure PRICE-REPORT, DATATRIEVE displays three 
fields for each YACHTS record. First the builder and model are displayed as a 
result of the procedure's PRINT statement. Then the PRICE_PERJPOUND pro- 
cedure is called to compute and format the price/displacement before it is 
displayed. 

The following example uses the BIG_ YACHTS procedure to establish the 
CURRENT collection and PRICE-REPORT to print a short report: 

DTR > : B I G_YACHTS 5 : PR I CE_RE P0RT(rejj 



MANUFACTURER 



MODEL 



RIG 



LENGTH 
OVER 
ALL 



WEIGHT BEAM 



PRICE 



CHALLENGER 



41 
41 
41 



KETCH 
SLOOP 
KETCH 
KETCH 
SLOOP 
SLOOP 
KETCH 
KETCH 



41 
41 
41 
41 
41 
41 
42 
42 



2B »700 

20 ,700 
22 »000 
22 * 

17 >750 

18 »000 
24 >250 

21 ,000 



13 
11 
12 
13 
12 
1 1 
13 
13 



$51 >228 
$48 >490 
$41 ,350 
$54 ,370 



COLUMBIA 

GULFSTAR 

ISLANDER 

NAUTOR 

NEWPORT 

OLYMPIC 

PEARSON 



FREEPORT 
SWAN 41 
41 S 

ADVENTURE 
419 



$80 #500 



(continued on next page) 
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PRICE 
PER 

MANUFACTURER MODEL POUND 



CHALLENGER 


41 


$1 i 


,92 


COLUMBIA 


41 


$2 , 


,34 


GULFSTAR 


41 


$1 < 


,88 


ISLANDER 


FREEPORT 


$2, 


,50 


NAUTOR 


SWAN 41 


$0 < 


> 


NEWPORT 


41 S 


$0 < 


> 00 


OLYMPIC 


ADVENTURE 


*3< 


• 32 


PEARSON 


419 


$0, 


> 00 



DTR > EXIT(ret) 

When nesting procedures, do not let a procedure invoke itself. You can create an 
infinite loop. (Should you create such a loop, press CTRL/C two times to stop your 
process.) 

9.7 Using a Procedure in a Compound Statement 

To execute a procedure a number of times, you can invoke it in a REPEAT or 
FOR statement. You should be careful when invoking a procedure in these state- 
ments, however. For example, the following procedure appears to be correct but 
produces unexpected results: 

DTR > SHOW EX 1 (RED 
PROCEDURE EX1 
FOR 

YACHTS WITH PRICE = AND LOA BT IB AND 23 
PRINT BUILDER t MODEL, LOA 
PRINT "Printing Test Record" 
END-PROCEDURE 

DTR > REPEAT 3 :EX1 

LENGTH 
OVER 



MANUFACTURER 


MODEL 


ALL 


ENCHILADA 


20 




20 


ERICSON 


23/ 


SPECIA 


23 


SAN JUAN 


21 




21 


ENCHILADA 


20 




20 


ERICSON 


23/ 


SPECIA 


23 


SAN JUAN 


21 




21 


ENCHILADA 


20 




20 


ERICSON 


23/ 


SPECIA 


23 


SAN JUAN 


21 




21 



Printing Test Record 

Only the FOR statement in the EX1 procedure is repeated. The PRINT state- 
ment is executed only once at the very end. When DATATRIE VE encounters the 
first complete statement in a procedure, it assumes that the REPEAT statement 
is also complete. Therefore, it repeats only the first statement in the procedure 
and executes each of the remaining statements once. 
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To repeat the entire procedure, enclose the procedure call or the procedure defini- 
tion in a BEGIN-END block. For example, the following sequence of statements 
puts a procedure in a BEGIN-END block and repeats the procedure three times: 



DTR > REPEAT 3 BEGIN© 
[Looking for statement] 
CON> :EXl(!jj 
CQN> END© 



MANUFACTURER MODEL 

ENCHILADA 20 
ERICSON 23/ SPECIA 

SAN JUAN 21 
Printing Test Record 
ENCHILADA 20 
ERICSON 23/ SPECIA 

SAN JUAN 21 
Printing Test Record 
ENCHILADA 20 
ERICSON 23/ SPECIA 

SAN JUAN 21 
Printing Test Record 

The following example uses a FOR statement, includes a BEGIN-END block in 
the procedure, and invokes the procedure in a REPEAT statement: 



DTR> SHOW EX3(ret) 
PROCEDURE EX3 
FOR 

YACHTS WITH PRICE = AND LOA BT IS AND 23 
BEGIN 

PRINT BUILDER* MODEL > LOA 
PRINT "Print Test Record" 

END 

END-PROCEDURE 



LENGTH 
OVER 
ALL 

20 
23 
21 

20 
23 
21 

20 
23 
21 



DTR > REPEAT 3 :EX3(RETj 

LENGTH 
OYER 

MANUFACTURER MODEL ALL 



ENCHILADA 


20 


20 


Print Test 


Record 




ERICSON 


23/ SPECIA 


23 


Print Test 


Record 




SAN JUAN 


21 


21 


Print Test 


Record 




ENCHILADA 


20 


20 


Print Test 


Record 




ERICSON 


23/ SPECIA 


23 


Print Test 


Record 




SAN JUAN 


21 


21 


Print Test 


Record 




ENCHILADA 


20 


20 


Print Test 


Record 





(continued on next page) 
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ERICSON 23/ SPECIA 23 

Print Test Record 

SAN JUAN 21 21 
Print Test Record 

DTR > 

If you invoke a procedure in a FOR statement, you must use the same technique. 
Enclose the call or the procedure definition in a BEGIN-END block as in the fol- 
lowing example: 

DTR > SHOW PRICE_REP0RT2(RETj 
PROCEDURE PR I CE-REP0RT2 

PRINT BUILDER* MODEL * : PR I CE_PER_ POUND 
END-PROCEDURE 

DTR > 

DTR > FOR YACHTS WITH PRICE GT 20000 AND LOA LT 23® 

[Looking for statement] 

C0N> BEG I N(ret) 

[Looking for statement] 

C0N> : PR I CE_REP0RT2(rejJ 

[Looking for statement or "END"] 

C0N> END© 







PRICE 






PER 


MANUFACTURER 


MODEL 


POUND 


CAPE DORY 


28 


$2 . aa 


SABRE 


28 


$2,97 



DTR > 



Remember that if you use a procedure in a loop, do not include a FIND, SELECT, 
DROP, or RELEASE statement. These statements cannot appear in BEGIN- 
END blocks. 

9.8 Aborting Procedures 

You can abort a procedure by including a SET ABORT statement in the proce- 
dure definition. If the abort conditions arise and SET ABORT is in effect, 
DATATRIEVE aborts the procedure and prints a message on your terminal. If 
SET NO ABORT is in effect, DATATRIEVE aborts the command or statement 
that contains the ABORT but continues to execute the other commands and 
statements in the procedure. 
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The default setting in DATATRIEVE is SET ABORT. You can ensure that SET 
ABORT is in effect by including that statement in the procedure definition: 

DTR > DEFINE PROCEDURE BIG_YACHTS_QUER Y©) 

DFN > SET ABORT© 

DFN > DECLARE LENGTH PIC 39© 

DFN > UALID IF LENGTH GT 35. (ret) 

DFN > LENGTH = * . " M I N LOA"© 

DFN > IF LENGTH GT 42© 

DFN > THEN ABORT "NO BOATS THAT BIG"© 

DFN > FIND BIGGIES IN YACHTS WITH LOA GE LENGTH© 

DFN > SORTED BY BUILDER© 

DFN > PRINT BUILDER* RIG* LOA t PRICE OF BIGGIES© 
DFN > END_ PROCEDURE©) 
DTR > 

If you invoke BIG_ YACHTS-QUERY and supply a length of 35 or smaller, 
DATATRIEVE reprompts you for a valid length. If you supply a length greater 
than 42, the procedure aborts, prints the specified abort message, and returns 
you to DATATRIEVE command level: 

DTR > :BIG_YACHTS_QUERY© 
Enter MIN LOA: 35© 
Validation error for LENGTH 
Re-enter MIN LOA: 43© 
ABORT: NO BOATS THAT BIG 

Execution terminated by "ABORT" statement 
DTR > 

If you assign a value between 36 and 42 to length, DATATRIEVE prints the 
appropriate collection: 



DTR > :BIG_YACHTS_OUERY© 
Enter MIN LOA: 39© 







LENGTH 










OUER 






MANUFACTURER 


RIG 


ALL 


PRICE 


BLOCK I . 


SLOOP 


39 






CHALLENGER 


KETCH 


41 


$51 


,228 


COLUMBIA 


SLOOP 


41 


$48 


,490 


GULFSTAR 


KETCH 


41 


$41 


,350 


ISLANDER 


KETCH 


41 


$54 


,970 


LINDSEY 


MS 


39 


$35 


>900 


NAUTOR 


SLOOP 


41 






NEWPORT 


SLOOP 


41 






OLYMPIC 


KETCH 


42 


$80 


»500 


PEARSON 


SLOOP 


39 






PEARSON 


KETCH 


42 







Maintaining Procedures 

You can maintain the procedures stored in your default dictionary directory with 
the SHOW, EDIT, and DELETE commands. 
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9.9.1 Displaying Procedure Names 



You can list the names of all procedures in your default directory with the SHOW 
command: 

DTR > SHOW PROCEDURES© 
Procedures: 
BIG 

MS-SEARCH 

DTR> 

9.9.2 Displaying Complete Procedures 

If you want to display a procedure on your terminal, you can use the SHOW com- 
mand and specify the name of the procedure to be displayed: 

DTR > SHOW MS_SEARCH(ret) 
PROCEDURE MS-SEARCH 
READY YACHTS 

FIND YACHTS WITH RIG = "MS" 

FOR CURRENT PRINT BUILDER* 

(BUILDER VIA COMPANY-TABLE) ("ADDRESS") 

END-PROCEDURE 

DTR> 

9.10 Editing Procedures 

You can correct an error with the DATATRIEVE Editor. Invoke the Editor with 
the following command at the DTR> prompt: 

EDIT procedure-name 

When you find the error, use the DATATRIEVE Editor to correct it or follow this 
sequence: 

1. EXTRACT the procedure from DATATRIEVE to a command file on your sys- 
tem using the following statement: 

EXTRACT ON file-spec procedure-name 

Use the file extension .CMD in the file specification to distinguish the 
extracted file as a command file. 

2. Exit from DATATRIEVE. 

3. Use the text editor you normally use on your system to revise the command 
file containing the procedure. 

4. Return to DATATRIEVE. 

5. Invoke the command file by typing the at sign (@) and the name of the file to 
bring the corrected procedure into DATATRIEVE. 



BIG_ YACHTS-QUERY CHEAP 
PHONE-REP TEST YACHT-SUMMARY 
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See the following chapter for information on DATATRIEVE command files and 
Chapter 16 in this manual for information on DATATRIEVE Editor commands. 



9.10.1 Deleting Procedures 

You can delete a procedure from your dictionary with the DELETE command: 

DTR > SHOW PROCEDURES© 
Procedures: 

BIG BIG_ YACHTS- QUERY CHEAP 

MS-SEARCH PHONE-REP Y ACHT-SUMNARY 



DTR > DELETE BIG?© 
DTR > SHOW PROCEDURES© 
Procedures: 

BIG_YACHTS_QUERY 

PHONE-REP 



CHEAP MS-SEARCH 
YACHT-SUMMARY 



DTR > 



Note that the DELETE command must end with a semicolon (;). 

You should maintain a backup copy of your procedure, especially if it is a long 
one. Use the DATATRIEVE EXTRACT command to copy your procedure to a 
command file for backup. Once you have a backup copy, you can always recover 
the procedure if you happen to delete it accidentally. 

The following example illustrates how you can create a backup file, delete a pro- 
cedure, and replace it without ever leaving DATATRIEVE: 



DTR> SET COLUMNS-PAGE 
DTR > SHOW PROCEDURES© 
Procedures: 

BIG_YACHTS 

BREAK-REP 

FAM-REC 

MULTIPLE-PRINT 

P 

R 

SALARY-TOTALS 

TITLE-PAGE 

XP 

DTR > EXTRACT ON SAUBIG 

DTR > DELETE BIG- YACHTS. 

DTR> SHOW PROCEDURES© 

Procedures: 

BIG_YACHTS 
EXPENSIVE 
JOB-HISTORY 
NME 

PRICE-INCREASE 
SALARY -REP0RT2 
TEST-WAGE 
WP 

YACHT-PRICE 



= 80© 



BIG_YACHTS_QUERY 
CTRL 

INFLATION-REPORT 

MULTIPLE-STORE 

PAGE-HEADER 

SALARY-REPORT 

SUM 

y 

YACHTS-REPORT 
BIG_YACHTS_QUERY© 
.QUERY 5© 



EXPENSIVE 

NEW_YACHTS 

PICKBOATS 

SALARY-REPORTi 

TAB-TEST 

WAGE-REPORT 

YACHT_PER_LB 



BP 
F 

MULTIPLE-PRINT 

P 

R 

SALARY-TOTALS 
TITLE-PAGE 



BREAK-REP 
FAM-REC 

MULTIPLE-STORE 

PAGE-HEADER 

SALARY-REPORT 

SUM 

y 

YACHTS-REPORT 



BP 
F 

JOB-HISTORY 
NME 

PRICE-INCREASE 
SALARY -REP0RT2 
TEST-WAGE 
WP 

YACHT-PRICE 



CTRL 

INFLATION-REPORT 

NEW_YACHTS 

PICKBOATS 

SALARY-REPORTI 

TAB-TEST 

WAGE-REPORT 

YACHT_PER_LB 



(continued on next page) 
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DTR > 0SAVBIG 

DELETE BIG_YACHTS_QUERY5 

"BIG_ YACHTS-QUERY" has not been defined 
DEFINE PROCEDURE B I G_ YACHTS-QUERY 
SET ABORT 

DECLARE LENGTH PIC 99 
VALID IF LENGTH GT 35. 
LENGTH = *."MIN LOA" 
IF LENGTH GT 42 

THEN ABORT "NO BOATS THAT BIG" 

FIND BIGGIES IN YACHTS WITH LOA GE LENGTH 

PRINT BUILDER* RIG> LOA t PRICE OF BIGGIES 

END-PROCEDURE 

DTR > SHOW PROCEDURES© 

Procedures: 

B I G-YACHTS 

BREAK-REP 

FAM-REC 

MULTIPLE-PRINT 
P 
R 

SALARY-TOTALS 
TITLE-PAGE 
XP 

DTR > :BIG_YACHTS_OUER Y(ret) 
Enter MI N LOA: "Z 
Execution terminated by operator 
DTR > 



in the dictionary 



SORTED BY BUILDER 



BIG_YACHTS_QUERY 
CTRL 

INFLATION-REPORT 

MULTIPLE-STORE 

PAGE-HEADER 

SALARY-REPORT 

SUM 

V 

YACHTS-REPORT 



EXPENSIVE 

NEW_YACHTS 

PICKBOATS 

SALARY -REPORT1 

TAB-TEST 

WAGE-REPORT 

YACHT_PER_LB 



BP 
F 

JOB-HISTORY 
NME 

PRICE-INCREASE 
SALARY -REP0RT2 
TEST-WAGE 
WP 

YACHT-PRICE 
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Using DATATRIEVE Command Files 



Many people use DATATRIEVE by typing in single commands in the form 
@ENTERC or :MONTHLY_REPORT and then watching the results scroll on 
their screens. Someone else has prepared a command file or procedure for them. 
Within the command file or procedure are the DATATRIEVE commands and 
statements to carry out a given task. 

Command files are much like procedures. Both contain fixed sequences of 
DATATRIEVE commands and statements and both allow you to execute fre- 
quently used operations. They have the following differences: 

• You invoke a command file by typing the at sign (@) before the file specifica- 
tion, a procedure by typing a colon (:) before the procedure name. 

• You store the procedures in your dictionary. You can see your procedures with 
a SHOW PROCEDURES command from within DATATRIEVE. Your com- 
mand files, on the other hand, reside outside DATATRIEVE in your operating 
system directory. You must exit from DATATRIEVE and use operating system 
commands to display them. 

• You edit procedures with the DATATRIEVE Editor, command files with your 
operating system editor. 

• When you invoke command files, you see the command statements and com- 
ments echo on your terminal. 

You can use command files for the following purposes: 

• To create a startup command file that will automatically execute certain com- 
mands and statements each time you invoke DATATRIEVE. Default name for 
the file is QUERY.INI. See Chapter 2. 

• To create and then invoke command files to add definitions of dictionary 
objects to your dictionary. 
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• To use as backup files of your dictionary. If something happens to corrupt the 
dictionary and you need to restore the definitions it previously contained, you 
can use your backup files of domain, record, table, and procedure definitions. 

DATATRIEVE executes the command file and returns to your operating sys- 
tem's command level. 

• To process files in batch mode. You can include invocation command lines to 
execute DATATRIEVE commands and statements. 

• To develop and test a procedure you want to store in your dictionary: 

1. Put the steps of the procedure into a command file. Do not yet include the 
DEFINE PROCEDURE command. 

2. Execute the command file from your operating system's command level. 

3. The steps in the command file will appear on the screen and stop at the 
point where an error occurs. Use the message to help you decide what is 
wrong with the series of statements you have entered. 

4. When you have eliminated all errors from the command file, insert a 
DEFINE PROCEDURE statement at the beginning of the file and an 
END-PROCEDURE statement at the end of the file. If you have an earlier 
version of the procedure or another element with the same name that you 
do not need any more, insert a DELETE command and the file name before 
the DEFINE PROCEDURE statement. Be careful not to delete anything 
important, however. 

5. Execute the command file by typing an at sign (@) and the file name to load 
the procedure into your dictionary. 

10.1 Creating a Command File 

You create a command file at the operating system level with a text editor. 
Invoke an editor and enter the sequence of DATATRIEVE commands and state- 
ments just as you would in DATATRIEVE. Do not include DATATRIEVE 
prompts such as DTR>, CON>, DFN>, or RW>, only the commands and state- 
ments you enter following a prompt. When you complete the sequence of com- 
mands and statements and exit from the editor, your operating system stores the 
command file in your system directory. 

It is usually a good idea to specify .CMD as the file extension of a DATATRIEVE 
command file. Because it is the default file extension, you do not have to type the 
.CMD extension when you invoke the command file in DATATRIEVE. For exam- 
ple, to invoke the command file HELLO.CMD in DATATRIEVE, you can type 
the following: 

DTR> SHELLD 
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1 0.2 Contents of a Command File 



A command file can contain any DATATRIEVE command or statement. 

1 0.2.1 ADT, EDIT, SET GUIDE 

You can include ADT, EDIT, or SET GUIDE commands in a command file. 
DATATRIEVE places you in ADT, edit, or Guide mode and displays an ADT, 
edit, or Guide prompt. You cannot include a response to the Guide prompt in 
your command file, however. The file can contain only commands or statements. 

DATATRIEVE executes the next line in the command file only after you exit 
from the DATATRIEVE Editor, Guide mode, or ADT. Even if that line is a valid 
response to an ADT, edit, or Guide mode prompt, DATATRIEVE displays an 
error message and returns you to DATATRIEVE command level unless it is a 
valid DATATRIEVE command or statement. 

10.2.2 Comments 

You can include comments in a command file by placing an exclamation point (!) 
before each comment line. Comments echo on your terminal when you invoke 
the file. 

If your command file defines a procedure and you put comments into the proce- 
dure definition, DATATRIEVE stores the comments in the dictionary along with 
the rest of the definition. DATATRIEVE displays those comments when you 
invoke the command file. When you invoke the procedure, however, 
DATATRIEVE does not display the comments on your terminal. 

10.3 Invoking a Command File 

To invoke a command file that you have catalogued in your directory, precede the 
file specification with an at sign (@). To invoke a command file, enter the invoca- 
tion on a line by itself. For RSTS systems, use this format: 

@device:[PPN]filename.cmd 

For RSX systems, use this format: 

@device:[UIC]filename.cmd;version 

If the file extension is .CMD and the file is in your default directory, you need 
enter only the file name: 

©filename 
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10.3.1 Invocation Command Lines 



You need not e±iter DATATRIEVE to invoke a command file. You can invoke a 
command file from the system level. For example, to invoke PRT.CMD in your 
operating system directory, type this in response to the system level prompt (>): 



Ready 

> DTR @PRT© 

Invoking a command file in this way differs from invoking one in response to the 
DTR> prompt. DATATRIEVE executes all the commands and statements in the 
command file as though you had entered them interactively. However, it does not 
print the DTR> prompt on your terminal and after executing the last command 
or statement in the file, it automatically exits from DATATRIEVE. If the com- 
mand file is in another user's directory, you invoke it by specifying all the neces- 
sary information in the following format: 

@device:[UIC]filename.extension 

For RSX systems, you can also specify a version number after the extension. 



1 0.3.2 Invoking a Command File from a Procedure 

You can invoke a command file from a procedure you define with the DEFINE 
PROCEDURE command. For example, suppose you create a procedure 
PICKBOATS to form a collection of boats that cost more than $10,000. Invoke a 
command file SAMPLE.CMD containing report-generating statements within 
PICKBOATS to produce a report: 

DTR > DEFINE PROCEDURE PICKBOATS® 
DFN> READY YACHTS© 

DFN > FIND YACHTS WITH PRICE GT 10000 SORTED BY L0A » BEAM© 
DFN > 0SAMPLE©) 
SET ABORT 

!THIS REPORT REQUIRES AN ESTABLISHED COLLECTION* 

! SORTED BY L0A AND BEAM. 

! 

! HAVE YOU ESTABLISHED A COLLECTION? 

IF *."YES OR NO" CONTAINING "N" THEN ABORT "SORRY > NO COLLECTION," 
REPORT ON *. "OUTPUT DEVICE OR FILE" 

SET REPORT_NAME=" SAMPLE REPORT "/"FROM A PROCEDURE" 

SET LINES_PAGE=55 * C0LUMNS_PAGE=B0 

PRINT BUILDER* MODEL* LOA > BEAM* PRICE 

AT BOTTOM OF LOA PRINT SKIP* "AVERAGE PRICE ="» 

AVERAGE ( PRICE) » SKIP 
AT BOTTOM OF REPORT PRINT COL 17* "NUMBER OF BOATS = "* 

COL 40* COUNT* SKIP* "AVERAGE PRICE OF ALL BOATS ="» AVERAGE (PRICE) 
END-REPORT 

DFN > END_ PROCEDURE©) 

DTR > : PICKBOATS© 

Enter YES OR NO: Y© 

Enter OUTPUT DEVICE OR FILE: TI:© 

DTR > 

(continued on next page) 
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SAMPLE 


REPORT 


25 


-AU3-82 




cpnM A 

P 1^ U M rl 






P n da 1 

r a a c i 






l. c iM u i n 










OVER 






M A l\l 1 1 F A P T 1 1 R F R 

I I ri i N Li i ri i_» I Linen 


MODEL 


Al 1 

M L_ L_ 


RF AM 

Lt C M 1 1 




FAQTLJARD 

L. n u | n n l \ L/ 


HO 


24 






AVERAGE PRICE = 








$15 >900 


IRWIN 


25 


25 


12 


$ 10 »950 


AVERAGE PRICE = 








$10 »950 


AMERICAN 


2S-MS 


2G 


08 


$18 ,895 


GRAMPIAN 


2B 


2G 


08 


$11 ,495 


WESTERLY 


CENTAUR 


2G 


08 


$15 ,245 


TANZER 


2G 


26 


09 


$11 ,750 


ALB I N 


73 


26 


10 


$17 ,900 



DTR > 

You cannot invoke command files while you are in ADT or Guide Mode. 

You can invoke a command file in response to the RW> prompt of the Report 
Writer. The file must begin with valid report statements. If you complete the 
report specification in the file with an END_REPORT statement, you can follow 
the specification with other valid DATATRIEVE commands or statements. When 
you invoke a command file, DATATRIEVE prints each command or statement on 
your terminal and executes it as if you had entered it directly from your key- 
board. If an error occurs, DATATRIEVE prints an error message and stops exe- 
cuting the command file. 

10.4 Aborting Command Files 

To abort a command file that may contain an error, include an ABORT state- 
ment in the file. If the responses meet the abort conditions and SET ABORT is in 
effect, DATATRIEVE aborts the command file and prints the message specified 
for the ABORT command. If SET NO ABORT is in effect, DATATRIEVE aborts 
the command or statement that contains the ABORT but continues to execute 
the commands and statements that follow in the file. 

1 0.5 Editing a Command File 

To edit a command file you must exit from DATATRIEVE and use a text editor. 
When you correct any error, return to DATATRIEVE, ready the necessary 
domains, establish any appropriate collections, and execute the command file 
again. 
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1 0.6 Sample Command File 



In contrast to the sample procedure, the sample command file prints each state- 
ment and command in the file as DATATRIEVE executes it. 

When DATATRIEVE encounters the statement with the * "YES OR NO" 
prompting value expression, it pauses to wait for your response to the question: 
HAVE YOU ESTABLISHED A COLLECTION? The Boolean expression 
CONTAINING checks your response to the question. If the response contains a 
letter N anywhere, the command file aborts. 

When DATATRIEVE encounters the *."OUTPUT DEVICE OR FILE" prompt, it 
pauses again for you to select the device or file for output of the report. 

Note that, except for the report name, the report the command file produces 
is the same as the one produced by the procedure YACHT-SUMMARY in 
Chapter 9. 

The file YSUM.CMD contains the following sequence of commands and 
statements: 

SET ABORT 

!THIS REPORT REQUIRES AN ESTABLISHED COLLECT I ON > 

! SORTED BY LOA AND BEAM. 

I 

SHAVE YOU ESTABLISHED A COLLECTION? 

IF *."YES OR NO" CONTAINING "N" THEN ABORT "SORRY* NO COLLECTION." 
REPORT ON *. "OUTPUT DEVICE OR FILE" 

SET REPORT_NAME= "SAMPLE REPORT "/" FROM A COMMAND FILE" 

SET LINES_PAGE=55 » C0LUMNS_PAGE=B0 

PRINT BUILDER* MODEL* LOA* BEAM* PRICE 

AT BOTTOM OF LOA PRINT SKIP* "AVERAGE PRICE ="» 

AVERAGE ( PRICE) * SKIP 
AT BOTTOM OF REPORT PRINT COL 13*"NUMBER OF BOATS = " * 

COL 33* COUNT* SKIP* "AVERAGE PRICE OF ALL BOATS ="* AVERAGE (PRICE) 
END-REPORT 

When you have readied the domain and established the appropriate collection, 
you invoke the command file with an at sign (@). You do not have to include the 
.CMD extension. DATATRIEVE prints each command and statement as it exe- 
cutes them: 

DTR > READY YACHTS® 

DTR > FIND FIRST 5 YACHTS WITH LOA BETWEEN 3G 37 AND PRICE NE 0(ret) 

[ 5 records found] 

DTR > SORT BY LOA* BEAM© 

DTR > @YSUM(ret) 

SET ABORT 

ITHIS REPORT REQUIRES AN ESTABLISHED COLLECTION* 

! SORTED BY LOA AND BEAM. 

I 

•HAVE YOU ESTABLISHED A COLLECTION? 

IF *."YES OR NO" CONTAINING " N " THEN ABORT "SORRY* NO COLLECTION." 

Enter YES OR NO: YES(ret) 

REPORT ON *♦ "OUTPUT DEVICE OR FILE" 

SET REPORT_NAME= "SAMPLE REPORT "/" FROM A COMMAND FILE" 
SET LINES_PAGE=55 » C0LUMNS_PAGE=B0 

(continued on next page) 
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PRINT BUILDER* MODEL > LOA > BEAM » PRICE 

AT BOTTOM OF LOA PRINT SKIP* "AVERAGE PRICE = "> 

AVERAGE (PRICE) * SKIP 
AT BOTTOM OF REPORT PRINT COL 17>"NUMBER OF BOATS = "> 

COL 40 > COUNT* SKIP* "AVERAGE PRICE OF ALL BOATS ="» AVERAGE (PRICE) 
END-REPORT 

Enter OUTPUT DEVICE OR FILE: TI:@ 



SAMPLE REPORT 
FROM A COMMAND FILE 



01-Ap r-87 
Pa3e 1 



MANUFACTURER 



MODEL 



LENGTH 
OVER 
ALL 



BEAM 



PRICE 



ISLANDER 
I . TRADER 



3B 
37 



3B 
3(3 



1 1 
12 



$31 *730 
$33 *500 



AVERAGE PRICE = 



$35 *S15 



IRWIN 

NORTHERN 

ALBERG 



37 MARK II 
37 

37 MK II 



37 
37 
37 



1 1 
1 1 
12 



$3B »350 
$50 >000 
$3G »951 



AVERAGE PRICE = 



$41 ,300 



NUMBER OF BOATS = 

AVERAGE PRICE OF ALL BOATS = 



$39 »02S 



10.7 Nesting Command Files Within Command Files 

You can invoke both procedures and command files from within a command file. 
For example, the command file MSMOD creates a loop with a FOR statement 
and then invokes the command file MOD. MOD contains a BEGIN-END block of 
statements that allows you to modify prices interactively: 

D T R > @MSM0D(Rl3 

READY YACHTS WRITE 

FOR YACHTS WITH RIG = "MS" 

@MOD 

BEGIN 
PRINT 

IF *."Y TO MODIFY j N TO SKIP" CONTAINING "Y" 
THEN MODIFY PRICE ELSE 
PRINT "NO CHANGE" 

IF *."Y TO CONTINUE* N TO ABORT" CONTAINING "N" 
ABORT "END OF PRICE CHANGES" 
END 

LENGTH 
OVER 

MANUFACTURER MODEL RIG ALL WEIGHT BEAM PRICE 

AMERICAN 2S-MS MS 2S 5*500 08 $18*950 

Enter Y TO MODIFY* N TO SKIP: Y(ret) 
Enter PRICE: 19350(ret) 

Enter Y TO CONTINUE* N TO ABORT: Y(reD 
EASTWARD HO MS 24 7*000 09 $15*900 

(continued on next page) 
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Enter Y TO MODIFY » N TO SKIP: N© 
NO CHANGE 

Enter Y TO CONTINUE* N TO ABORT: N© 

ABORT: END OF PRICE CHANGES 

DTR > FIND YACHTS WITH RIG = "MS"© 

C 5 records found] 

DTR > SELECT© 

DTR > PRINT© 

LENGTH 
OVER 

MANUFACTURER MODEL RIG ALL WEIGHT BEAM PRICE 

AMERICAN 2G-MS MS 2B 5*500 08 $13>350 

DTR > 

When nesting command files, do not allow a command file to invoke itself, either 
directly or indirectly. If you do, you receive this message: 



Comwand file nesting limit exceeded 



1 0.8 Using a Command File in a FOR or REPEAT Statement 

You can invoke a command file in a loop you create with the FOR or REPEAT 
statements. As the following example shows, you must be sure to invoke the 
command file on a separate line, and you must include its statements within a 
BEGIN-END block: 



DTR > SET NO PROMPT© 
DTR > READY YACHTS WRITE© 
DTR > FIND YACHTS WITH RIG = "KETCH"© 
C13 records found] 
DTR > FOR CURRENT @M0D© 
Expected statement* encountered " @ " ♦ 
DTR > FOR CURRENT© 
C0N> @M0D© 
BEGIN 
PRINT 

IF *."Y TO MODIFY* N TO SKIP" CONTAINING "Y" 
THEN MODIFY PRICE ELSE 
PRINT "NO CHANGE" 

IF *."Y TO CONTINUE* N TO ABORT" CONTAINING "N" 
ABORT "END OF PRICE CHANGES" 
END 

LENGTH 
OVER 

MANUFACTURER MODEL RIG ALL WEIGHT BEAM PRICE 

ALBERG 37 MK II KETCH 37 20*000 12 $3G*951 

Enter Y TO MODIFY* N TO SKIP: "Z 
Execution terminated by operator 
DTR > 
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Maintaining Command Files 



Your operating system directories, not the dictionary, store the command files. If 
you adopt the convention of using .CMD as the extension for command files, you 
can display the names of the command files on your terminal by requesting a 
directory listing of *.CMD at the command level. You can adopt any other con- 
vention you wish and use the wildcard in the same manner: 



READY 



>DIR *.CMD;(ret) 

Name .T/p Size Prot Date SY:C1,37] 

BLD11M.CMD 2 < G0> 24-Sep-B2 

CLASSE.CMD 3 < B0> 24-Sep-B2 

SAMPLE » CMD 4 < 60 > 24-Sep-82 



You can display the contents of a command file with the TYPE command at the 
system level: 



> TYPE SAMPLE.CMD ;© 
SET ABORT 

!THIS REPORT REQUIRES AN ESTABLISHED COLLECTION, 

! SORTED BY LOA AND BEAM. 

i 

!HAVE YOU ESTABLISHED A COLLECTION? 

IF *."YES OR NO" CONTAINING "N" THEN ABORT "SORRY, NO COLLECTION," 
REPORT ON *. "OUTPUT DEVICE OR FILE" 

SET REPORT_NAME= "SAMPLE REPORT "/" FROM A COMMAND FILE" 

SET LINES_PAGE = 55 , C0LUMNS_PAGE=G0 

PRINT BUILDER, MODEL, LOA, BEAM, PRICE 

AT BOTTOM OF LOA PRINT SKIP, "AVERAGE PRICE =", 

AVERAGE (PRICE) , SKIP 
AT BOTTOM OF REPORT PRINT COL 17, "NUMBER OF BOATS = ", 

COL 40, COUNT, SKIP, "AVERAGE PRICE OF ALL BOATS =", AVERAGE (PRICE) 
END-REPORT 



You can delete a command file from your directory with the operating system 
command level DELETE command. 



>DELETE SAMPLE . CMD 5 (ret) 
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Using DATATRIEVE Variables 



A variable is a symbol whose value can change as you execute a program. You 
can use the letter A as a variable, for instance. The name of the variable stays 
the same, but its value can change during a DATATRIEVE session. 

You use variables in DATATRIEVE: 

• To assign values to fields in STORE and MODIFY statements 

• As counters in FOR, REPEAT, and WHILE loops 

• As conditional values in Boolean expressions 

11.1 Declaring Variables 

You declare a variable with a statement in this form: 
DECLARE variable-name variable-definition 

The variable name is the name you give to the variable. The variable definition 
consists of field definition clauses. 

The following is an example of a DECLARE statement. Notice the similarity 
between the DECLARE statement and the definition of a field in a record: 

DTR > DECLARE X PIC 9(7) V99 ED I T_STR I NG IS $$,$$$»$$$ , 99 . 

When you declare a variable, you can use any of the DATATRIEVE field 
definition clauses except OCCURS and REDEFINES. You must include at 
least one PIC, COMPUTED BY or USAGE clause. You can also use the 
QUERY-HEADER, QUERY-NAME, EDIT-STRING, VALID IF, and SIGN 
clauses. 
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11 .2 Assigning Values to Variables 



DATATRIEVE assigns a starting value to, or initializes, variables at the time 
you create them. Numeric variables are initialized to the value 0. Alphabetic or 
alphanumeric string variables are initialized to a blank field (spaces). You can 
assign an initial value of to numeric fields or space to string fields, but it is not 
necessary to do this. Of course, you must always initialize a variable when you 
want the starting value to be other than the DATATRIEVE default. 

In most cases, you use the assignment statement ( = ) to give a value to a varia- 
ble. The assignment statement takes the following form: 

variable-name = value-expression 

Variable name is the name you gave the variable in the DECLARE statement. 
Value expression can be any one of the following: 

• A literal 

• A field name 

• Another variable 

• A prompting value expression 

• Values from a table 

• A statistical function 

• An arithmetic expression 

• A concatenated expression 

Remember, however, to assign a value that is consistent with the definition of 
the variable. If you assign a value that is larger or a different data type than you 
specified in the PIC or USAGE clauses, your results might not be what you 
intended. 

You can also use the assignment statement to change the value of a variable at 
any time after initialization. The following example declares a variable, prints 
its initial value, then changes its value using two methods: 

DTR > DECLARE X PIC 939 ED I T_STR I NG 229,© 
DTR > PRINT X(ret) 

A 



DTR > X = 23 5 PRINT X(ret) 
v 

23 

(continued on next page) 
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DTR > X = *. "VALUE FOR X"(ret) 
Enter VALUE FOR X: 45G(ret) 
DTR > PRINT X <->(H) 

ass 

DTR > 

The minus sign ( - ) in the preceding example suppresses the heading, in this 
case the name of the variable (X), in a PRINT statement. 

The following example illustrates another way of assigning values to a variable. 
In the example, the procedure NAME_LIST creates a variable (NEAT_NAME). 
The values of the variable are supplied from the PERSONNEL domain and com- 
puted by two fields (FIRST_NAME and LAST_NAME) in the record definition 
for that domain. The values for the variable change as the values for the 
COMPUTED BY fields change. 

The procedure uses the variable both to restrict the print display to the two 
name fields in the record and to improve the appearance of each name by elimi- 
nating extra spaces between the first and last names: 

DTR > SHON NAME-LI ST(ret) 
PROCEDURE NAME-LIST 

DECLARE NEAT-NAME COMPUTED BY F I RST_NAME ! ! " " 1 LAST-NAME 

QUERY -HEADER IS "EMPLOYEE NAMES", 

READY PERSONNEL 

PRINT NEAT-NAME OF FIRST 2 PERSONNEL 

END-PROCEDURE 

DTR > : NAME-LIST© 

EMPLOYEE NAMES 

CHARLOTTE SPIVA 
FRED HOWL 

DTR > 

11 .3 Local and Global Variables 

You can define two kinds of variables in DATATRIEVE: 

• Global 

• Local 

You use the DECLARE statement to define both local and global variables. A 
variable you define with a BEGIN-END block is a local variable, and you can use 
it only within that block. A variable you define at DATATRIEVE command level 
is a global variable. It remains in your workspace until you release it or exit 
from DATATRIEVE. Use the assignment statement (variable = value) to set the 
variable equal to a particular value. 
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11.3.1 Global Variables 



You can use a global variable to change values in every record in a domain. Sup- 
pose you want to assign to each boat in YACHTS a new price that is two-thirds of 
the present price. By using a COMPUTED BY clause in a global variable, you 
can apply a single formula to every yacht, as in the example that follows: 



DTR> READY YACHTS MODIFY 


(RET) 
















DTR > DECLARE SALE-PRICE 


COMPUTED BY 


PRICE/1 ,! 












CON> EDIT-STRING IS $Z9 » 


999 # 99 » (ret) 














DTR > SALE-PRICE = 0(ret) 


















DTR > FOR FIRST 5 YACHTS 


PRINT 


BOAT > 


SALE-PRICE© 














LENGT 


H 
















OVER 










SALE 




MANUFACTURER MODEL 


RIG 


ALL 


WEIGHT 


BEAM 


PRICE 


PRICE 




ALBERG 37 MK II 


KETCH 


37 


20 »000 


12 


$3B 


»951 


$24 »B34< 


,00 


ALB I N 79 


SLOOP 


2G 


a »200 


10 


$17 


»900 


$11 >933< 


• 33 


ALBIN BALLAD 


SLOOP 


30 


7 ,276 


10 


$27 


»500 


$18 #333< 


• 33 


ALB IN MEGA 


SLOOP 


27 


5 »070 


08 


$18 


#600 


$12 »400< 


,00 


AMERICAN 2G 


SLOOP 


2B 


i\ f 000 


08 


$9 


,895 


$ 6 »59G< 


,87 



DTR > 



The variable SALE-PRICE declared at DATATRIEVE command level remains 
in the workspace throughout the session. It changes its value whenever the 
value of PRICE changes. The variable remains in your workspace until you 
release it with the RELEASE command or declare another variable with the 
same name. 

11.3.2 Local Variables 

You define local variables with DECLARE statements entered in BEGIN-END 
blocks and THEN statements. The local variable has an effect only within the 
clause or statement in which you declare it. 

In the following example, the local variable declared in the inner statement 
supersedes one with the same name declared in an outer statement. Notice that 
the different value or different data type assigned to the inner variable has no 
effect on the value of the variable in the outer statement. Note also that neither 
local variable exists when DATATRIEVE finishes executing the compound state- 
ments containing them both: 

DTR > SET NO PROMPT (ret) 
DTR > BEGIN(ret) 

C0N> DECLARE X PIC XXX, (ret) 
C0N> X = " TOP "(RET) 
C0N> PRINT X(ret) 
C0N> BEGIN© 

C0N> DECLARE X PIC 9 « 99 « (RET) 

C0N> X = 1.23d?) 

C0N> PRINT )<m 

C0N> END(ret) 

(continued on next page) 
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CON> PRINT )•( (ret) 
CON> END(ret) 



TOP 

X 

1 .23 

\/ 
/\ 

TOP 

DTR > PRINT )<m 

Field " X " is undefined or used out of context 
DTR > 

If you declare a global variable and then use the same name for local variables, 
the value of the global variable is not affected by value assignments and changes 
made to its local counterpart(s). 

1 1 .4 Using Variables to Assign Values to Fields 

You can use variables to assign values to fields in the USING clauses of STORE 
and MODIFY statements. You cannot, however, use a variable to respond to a 
prompt for a field value, whether the prompt is the result of the syntax of the 
STORE or MODIFY statement or of a prompting value expression. 

In USING clauses of STORE and MODIFY statements, you can use value 
expressions on the right side of assignment statements to supply values for 
fields. In some circumstances, you can use variables in those assignments to con- 
trol the uniformity of input data. 

In this example, WORK is a domain you want to contain uniform names. The 
data file is indexed on WHO and allows duplicates: 

DTR > SHOW WORK_REC(rD 
RECORD W0RK_REC 

USING 
01 TOP, 

03 JOB PIC X( 15) . 
03 RESPONSIBLE-PERSON PIC X(4) 
QUERY -NAME WHO . 

5 

DTR > 
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NAME_TABLE translates the varying inputs into uniform values to store in the 
work domain: 



SHOW NAME_TABLE(ret) 
E NAME-TABLE 



DTR > 
TABL 
E 

ED 
EM 
M 
F 

FH 

FRED 
H 
L 
R 

RBL 
RICK 
RL 

ELSE 
END-TABLE 



ED » 

ED , 

ED t 

ED t 

FRED 

FRED 

FRED 

FRED 

RICK 

RICK 

RICK 

RICK 

RICK 



" *3 r? o n> " 



In the following STORE statement, the USING clause uses the variable 
PERSON with a prompting value expression for the responsible person. The 
table translates the value supplied to that prompt and stores the uniform results 
in the field WHO. 



DTR > SET NO PROMPT© 

DTR> DECLARE PERSON PIC )<(5),(ret) 

DTR > READY WORK WRITE® 

DTR > REPEAT 3 STORE WORK USING© 

C0N> BEG I N(ret) 

CON> JOB = *.J0BdT) 

CON> PERSON = *.WHO(ret) 

CON> WHO = PERSON MIA NAME_TABLE(ret) 

CON> END(ret) 

Enter JOB: CLEAN I NG(ret) 
Enter WHO : E(ret) 
Enter JOB: DRYING© 
Enter WHO: FR(ret) 
Enter JOB: SELLING© 
Enter WHO: R© 
DTR > PRINT WORK© 

RESPONSIBLE 
JOB PERSON 

CLEANING ED 
DRYING ???? 
SELLING RICK 

DTR > 



1 1 .5 Using Variables as Counters to Control Record Streams 

You can use a counter to keep track of how many times DATATRIEVE performs 
a task. When you use a counter to control a record stream, however, it can also 
limit the number of times DATATRIEVE executes FOR and WHILE statements. 
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Suppose you want to keep a running count of the yachts you are repricing. You 
can use the following global variable: 

DTR > DECLARE A PIC 999. (ret) 
DTR > A = 0(ret) 
DTR > PRINT A (ret) 

A 

000 

DTR > SET NO PROMPT® 
DTR > FOR YACHTS© 
C0N> BEGIN© 
C0N> A = A + 1 (ret) 
C0N> PRINT A» BOAT© 

C0N> END 

LENGTH 











OVER 










A 


MANUFACTURER 


MODEL 


RIG 


ALL 


WEIGHT 


BEAM 


PRICE 


001 


ALBERG 


37 MK II 


KETCH 


37 


20 #000 


12 


$3G 


#951 


002 


ALB I N 


79 


SLOOP 


2B 


a #200 


10 


$17 


#900 


003 


ALB I N 


BALLAD 


SLOOP 


30 


7 #27G 


10 


$27 


#500 


004 


ALB I N 


VEGA 


SLOOP 


27 


5 #070 


08 


$18 


# GOO 


005 


AMERICAN 


26 


SLOOP 


2B 


a ,000 


08 


$9 


#895 


OOG 


AMERICAN 


26-MS 


MS 


2B 


5 #500 


08 


$18 


#895 


007 


BAYFIELD 
♦ 


30/32 


SLOOP 


32 


9 #500 


10 


$32 


#875 


113 


♦ 

WRIGHT 


SEAWIND II 


SLOOP 


32 


14 #900 


00 


$34 


#480 



DTR > 



In this example, you use the variable as a counter. Each time DATATRIEVE 
prints the corresponding record, it increases A by one. 

When you use a global variable as a counter in FOR and WHILE statements, 
you must initialize the variable to ensure that DATATRIEVE executes the loop 
the number of times you intend. If you use the same variable to control two 
loops, you must reinitialize the variable before DATATRIEVE executes the sec- 
ond loop. If you do not, DATATRIEVE may execute the loop fewer times than 
you intend. It may not execute the loop at all if the value of the variable is 
greater than the value specified in the IF-THEN-ELSE statement in the second 
loop. 

Either at the beginning or the end of the loop, you can use an IF-THEN-ELSE 
statement to evaluate the variable against a set of conditions. Depending on the 
evaluation, DATATRIEVE will continue the looping or execute an ABORT state- 
ment to end the loop. This example shows the use of a global variable to control a 
FOR statement and force an end to the loop: 

DTR> SET NO PROMPT© 
DTR > READY YACHTS© 
DTR> DECLARE B PIC 9.© 
DTR > B = 0© 

(continued on next page) 
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DTR > FOR YACHTS© 

CON> BEG I N©) 

CON> B = B + 1© 

CON> PRINT B# BOAT©) 

CON> IF B = 7 THEN ABORT "END OF LOOP"© 

CON> END© 



LENGTH 











OUER 










B 


MANUFACTURER 


MODEL 


RIG 


ALL 


WEIGHT 


BEAM 


PRICE 


1 


ALBERG 


37 MK II 


KETCH 


37 


20 #000 


12 


$36 


#951 


•j 


ALBIN 


79 


SLOOP 


2G 


a #200 


10 


$17 


#900 


3 


ALBIN 


BALLAD 


SLOOP 


30 


7 #276 


10 


$27 


#500 


a 


ALBIN 


MEGA 


SLOOP 


27 


5 f070 


OS 


$18 


#G00 


5 


AMERICAN 


2G 


SLOOP 


26 


a #000 


08 


$9 


#895 


G 


AMERICAN 


2G-MS 


MS 


26 


5 #500 


08 


$18 


#895 


7 


BAYFIELD 


30/32 


SLOOP 


32 


9 #500 


10 


$32 


#875 



ABORT: END OF LOOP 

Execution terminated by "ABORT" statement 
DTR > 

You can also assign a value greater than zero to the variable and use it as a 
decremental counter, as in this example: 



DTR > DECLARE A PIC 9. 

DTR > A = 8 

DTR > PRINT A (ret) 

A 

8 

DTR > SET NO PROMPT© 

DTR > FOR YACHTS© 

CON> BEGIN© 

CON> PRINT A# BOAT© 

CON> A = A - 1© 

CON> IF A = THEN ABORT "END 

CON> END© 



A 


MANUFACTURER 


MODEL 


RIG 


8 


ALBERG 


37 MK II 


KETCH 


7 


ALBIN 


79 


SLOOP 


6 


ALBIN 


BALLAD 


SLOOP 


5 


ALBIN 


MEGA 


SLOOP 


a 


AMERICAN 


26 


SLOOP 


3 


AMERICAN 


26-MS 


MS 




BAYFIELD 


30/32 


SLOOP 


1 


BLOCK I , 


40 


SLOOP 



ABORT: END OF LOOP 

Execution terminated by "ABORT" 

DTR > 



OF LOOP"© 



LENGTH 
OYER 

ALL WEIGHT BEAM PRICE 



37 


20 


> 


12 


$36 


#951 


26 


a 


# 2 


10 


$21 


#659 


30 


7 


#276 


10 


$27 


#500 


27 


5 


#070 


08 


$18 


#600 


26 


a 


#000 


08 


$9 


#895 


26 


5 


#500 


08 


$18 


#895 


32 


9 


#500 


10 


$32 


#875 


39 


18 


» 5 


12 


$29 


#050 



statement 
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The WHILE statement causes DATATRIEVE to repeat a statement as long as 
the condition specified in the Boolean expression is "true." The command file 
(WH.CMD) in this example uses a variable in a WHILE statement. 

DTR > @WH© 

DECLARE A USAGE INTEGER . 
A = 
PRINT A 

A 



FOR YACHTS 
WHILE A < 5 

BEGIN 

A = A + 1 

PRINT A» BOAT 

END 











LENGTH 
















OVER 










MANUFACTURER 


MODEL 


RIG 


ALL 


WEIGHT 


BEAM 


PRICE 


1 


ALBERG 


37 MK II 


KETCH 


37 


20 »000 


12 


$3B f951 




ALBERG 


37 MK II 


KETCH 


37 


20 »000 


12 


$3E ,951 


3 


ALBERG 


37 MK II 


KETCH 


37 


20 »000 


12 


$38 >951 


a 


ALBERG 


37 MK II 


KETCH 


37 


20 »000 


12 


$3B f951 


5 


ALBERG 


37 MK II 


KETCH 


37 


20 f 000 


12 


$3B »951 



DTR > 

The variable in the next example changes with the value expression 
PRICE/LOA and stops the FOR loop when the value expression meets the condi- 
tion specified in the IF-THEN-ELSE statement: 



DTR > SET NO PROMPT© 

DTR > FIND FIRST 15 YACHTS© 

[ 1 5 records found] 

DTR > DECLARE X PIC 9999 ED I T_STR I NG IS $$»$$$♦ 99 . © 

DTR > X = 0© 

DTR > FOR CURRENT© 

C0N> BEGIN© 

C0N> X = PRICE/LOA© 

C0N> PRINT TYPE* X ( " PR I CE " / " PER FOOT")© 

C0N> IF X GE 1000 THEN ABORT "TOO SHORT FOR THE MONEY 

C0N> END© 



MANUFACTURER 



MODEL 



PRICE 
PER FOOT 



ALBERG 

ALBIN 

ALBIN 

ALBIN 

AMERICAN 

AMERICAN 

BAYFIELD 



37 MK II 
79 

BALLAD 

MEGA 

2B 

2B-MS 
30/32 



$998 . 00 
$888 . 00 
$9 IB, 00 
$B88 . 00 
$380 . 00 
$726,00 
$1 »027 . 00 



ABORT: TOO SHORT FOR THE MONEY 

Execution terminated by "ABORT" statement 

DTR > 
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Using DATATRIEVE Tables 




Tables save space. They save space in record definitions and data files. They also 
save space when you type in commands and statements. With a DATATRIEVE 
table, you can associate codes with corresponding translations — for example, 
area codes with states and products with price codes. 

One advantage to such code and translation pairs is that you can substitute a 
short field for a long one. For instance, you can have a list of codes for job titles 
such that you can put E01 into the definition and have a table that translates the 
code into Tax Assessor First Class. A dictionary table looks like the sample in 
Figure 12-1. 



DICTIONARY TABLE 



Code 


Translation 


C 


"Customer Services" 


E 


Engineering 



Figure 12-1 : Code and Translation Pairs in a Dictionary Table 

12.1 A Sample Dictionary Table 

Suppose, for example, that you are a manufacturer who needs to order various 
items from clerks around the country. With the help of a DATATRIEVE table, 
you can use one command to find out which products have reached zero inven- 
tory, which clerks are responsible for the parts, and the phone numbers for those 
clerks. 



) 
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You can use a dictionary table, in this case a table called ORDER-TABLE, to 
pair clerks and phone numbers with the products you need to track. You can 
define a procedure to determine which items are out of stock, then invoke a table 
producing a list of clerks responsible for those parts. 

The following example uses the domain PRODUCTS and a procedure TAB, 
which finds the items no longer in stock and uses ORDER-TABLE to list the 
clerks you need to call: 

DTR> READY PRODUCTS© 
DTR > PRINT ALL PRODUCTS© 









PARTS 






PART 


IN 


VENDOR 


ITEM 


NUMBER 


STOCK 


ACME ASPHALT & SHINGLE 


ASPHALT 


1001 


3 


ACME ASPHALT & SHINGLE 


SHINGLES 


1002 





ACME ASPHALT & SHINGLE 


CUBE WALLS 


1003 


9999 


PURGE SYSTEMS 


ERASER-CHALK 


3001 


3 


PURGE SYSTEMS 


ERASER-PENCIL 


3002 


1 


PURGE SYSTEMS 


WHITE-OUT 


3003 


8645 


PURGE SYSTEMS 


MAGNETS-20 OZ. 


3004 





QUERY ENTERPRISES 


LISTINGS 


2001 


a 


QUERY ENTERPRISES 


REPORTS 


2002 





DTR > SHOW ORDER-TABLE® 








TABLE ORDER-TABLE 








"ACME ASPHALT & SHINGLE" 


: "L. LANDFILL 


(399) 555- 


1234" 


"QUERY ENTERPRISES" 


: "T. ABMOW (111) 555-432 


1 " * 


"PURGE SYSTEMS" 


: "T. SKWAIRDEE 


(123) 555 


-9876 


ELSE "SOMETHING ELSE" 








END-TABLE 








DTR > SHOW TABLET) 








PROCEDURE TAB 








FIND PRODUCTS WITH STOCK 


= SORTED BY PART 






FOR CURRENT PRINT ITEM* 


PART t 






VENDOR VIA ORDER-TABLE ( 


"CALL") USING ><(30> 







END-PROCEDURE 
DTR > :TAB(ret) 



ITEM 



PART 
NUMBER 



CALL 



SHINGLES 
REPORTS 
MAGNETS-20 03 



1002 L. LANDFILL (999) 555-1234 
2002 T. ABMOW (111) 555-4321 
3004 T. SKWAIRDEE (123) 555-9876 



DTR > 
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1 2.2 Creating Dictionary Tables 



To create a dictionary table, enter the DEFINE TABLE command: 
DEFINE TABLE table-name 

Then enter the pairs of codes and their translations on separate lines, separating 
them by a colon (:). Make sure to place a comma after each pair at the end of the 
line. 

If the code or the translation contains more than one word, enclose it in quota- 
tion marks. For example, the translation "New Hampshire" must be placed in 
quotation marks so DATATRIEVE will recognize the two words as one transla- 
tion entry. You must also use quotation marks to preserve lowercase letters in a 
code or translation. 

If you use quotation marks, the rules for character string literals apply. That is, 
neither the code nor the translation can exceed 132 characters, and neither can 
contain a RETURN, line feed, space, or control character. 

After the last code and translation pair, you can enter an optional ELSE clause. 
DATATRIEVE substitutes the translation in the ELSE clause for any values not 
found in the table. If your dictionary table does not contain an ELSE clause, 
DATATRIEVE prints an error message when it cannot find a value in the table. 

Translations included in an ELSE clause are also enclosed in quotation marks. 
Apply the same rules as with character string literals, except do not place a 
comma after an ELSE clause. 

To end a dictionary table definition, enter the keyword END-TABLE . The 
END_TABLE statement must follow the ELSE clause, if specified, or the last 
code and translation pair if there is no ELSE clause. If you omit the ELSE 
clause, do not put a comma after the last code and translation pair. 

After you enter the END_TABLE statement, DATATRIEVE stores the defini- 
tion in your current dictionary and creates an access control list for the diction- 
ary table. 

When you first refer to a table, DATATRIEVE searches the current data diction- 
ary for the table and loads it into your DATATRIEVE workspace. DATATRIEVE 
evaluates the value expression in your statement and compares the value with 
the codes in the table. The comparison is case sensitive and proceeds character- 
by-character. Thus, a value expression of 5 does not match a code of 05, and a 
value expression of Rig does not match a code of RIG. 

As you define a dictionary table, DATATRIEVE checks for syntax errors. For 
example, if you use a semicolon in place of the required colon, DATATRIEVE 
prints an error message and aborts the DEFINE TABLE command. 

DATATRIEVE does not store anything in the dictionary until you complete the 
table definition without a syntax error. You can use the DATATRIEVE Editor to 
change a table once it is in the dictionary. 



Using DATATRIEVE Tables 12-3 



If you want to edit the table as you create it, you can: 

• Enter one code and translation pair, finish the definition with END_TABLE, 
then use the DATATRIEVE Editor to extend the table to include additional 
code and tranlation pairs. 

• Leave DATATRIEVE and use the editor you usually use on your operating sys- 
tem to define the table in a command file. Then enter DATATRIEVE again and 
invoke the command file at the DTR> prompt. DATATRIEVE checks the syn- 
tax, and if the definition contains an error you can leave DATATRIEVE again 
and edit the command file. 

See Chapter 10 for more information about command files. 

1 2.3 Sample Dictionary Tables 

This section show ways you can define and use dictionary tables. 

For example, suppose you are a sales manager with a list of names and phone 
numbers of potential customers, and you want to know where they live. You can 
enter telephone area codes and their corresponding state names in a dictionary 
table, then refer to the table in a PRINT statement. 

You can define a dictionary table as follows: 



TABLE AREA_CODE_TABLE 
207 : MAINE* 
B03 : " NEW HAMPSHIRE" * 
802 : VERMONT * 

G17 : "EASTERN MASSACHUSETTS" > 

413 : "WESTERN MASSACHUSETTS"* 

401 : "RHODE ISLAND" * 

203 : CONNECTICUT* 

ELSE "NOT A VALID AREA CODE" 

END_TABLE 

Then you can prompt for an area code and print the corresponding state in a sin- 
gle statement: 



DTR > PRINT * . "AREA CODE" VIA AREA_CODE_TABLE USING X ( 2 1 ) @g) 
Enter AREA CODE: 203(ret) 
CONNECTICUT 
DTR > 

Suppose you also want to create a table of abbreviations for RIG, KETCH, 
SLOOP, and MS from the YACHTS domain. You can create the following diction- 
ary table, RIG_TABLE, and store it in the data dictionary for YACHTS: 

DTR > DEFINE TABLE R I G_TABLE(ret) 
DFN> "SLOOP " : "ONE-MAST" *(ret) 

DFN> "KETCH" : "TWO MASTS > BIG ONE IN FRONT" *(ret) 

DFN> "YAWL" : "SIMILAR TO KETCH"*© 

DFN > "MS" : "SAILS AND BIG MOTOR"*© 

DFN > ELSE "SOMETHING ELSE "(ret) 

DFN > END_TABLE(ret) 

DTR> 
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1 2.4 Using the IN Relational Operator with DATATRIEVE Tables 



You can use tables with the relational operators IN and NOT IN to set conditions 
in IF-THEN-ELSE statements and to validate data. The following is the general 
format for using IN and NOT IN with a DATATRIEVE table: 

field-name 

*. prompt [NOT] IN table-name 

variable-name 

1 2.4.1 Using a Table in a Record Selection Expression 

In a record selection expression, you can use a Boolean expression that refers to a 
dictionary table: 

DTR> FOR YACHTS WITH RIG NOT IN RIG-TABLE PRINT BOAT© 

LENGTH 
OVER 

MANUFACTURER MODEL RIG ALL WEIGHT BEAM PRICE 



AMERICAN 


26- 


MS 


MS 


2G 


5 


* 5 


08 


$18 


*895 


EASTWARD 


HO 




MS 


za 


7 


» 


09 


$15 


»900 


FJORD 


MS 


33 


MS 


33 


14 


> 


1 1 






LINDSEY 


33 




MS 


33 


14 


* 5 


12 


$35 


*900 


ROGGER FD 


M/S 




MS 


35 


17 


*600 


1 1 







DTR > FIND YACHTS WITH RIG IN R I G_TABLE(ret) 
C 1 8 records found] 
DTR > 



1 2.4.1 .1 Using a Table to Set Conditions in an IF-THEN-ELSE Statement — You can 

combine IN with a table reference to set the conditions of an IF-THEN-ELSE 
statement: 



DTR> SET NO PROMPT© 

DTR > FOR YACHTS WITH LOA = 26© 

C0N> BEGIN© 

C0N> PRINT© 

C0N> IF RIG NOT IN R I G_T ABLE© 

C0N> THEN ABORT "Does not meet requirements"© 
C0N> END© 

LENGTH 
OYER 

MANUFACTURER MODEL RIG ALL WEIGHT BEAM PRICE 



ALBIN 79 SLOOP 26 4*200 10 $17*900 

AMERICAN 2B SLOOP 2G 4*000 08 $9*895 

AMERICAN 2B-MS MS 2S 5*500 08 $18*895 

ABORT: Does not meet requirements 

Execution terminated by "ABORT" statement 

DTR> 



Using DATATRIEVE Tables 12-5 



1 2.4.1 .2 Using a VALID IF Clause with a Table to Validate Data — By referring to a 
dictionary table in a VALID IF clause, you can validate data in a field before 
storing the data. The VALID IF clause must be part of the record definition. The 
following definition of PHONE_REC illustrates this method of automatic data 
validation: 

DTR > DEFINE RECORD PHONE.REC USING© 

DFN > 01 PHONE ♦ (ret) 

DFN > 02 NAME PIC K(20).@et) 

DFN > 02 NUM6ER PIC 3(7) EDI T_STR I NG IS XXX - XXKK , (ret) 

DFN > 02 LOCATION PIC X<9).(ret) 

DFN > 02 DEPARTMENT PIC XX UAL ID I F(ret) 

DFN> DEPARTMENT IN DEPT.TABLE , (ret) 

DFN > 5(rct) 

DTR > 

The table DEPT_TABLE looks like this: 

DTR > SHOW DEPT_TABLE(rejj 
TABLE DEPT-TABLE 



" T 3 " 


"TYPESETTING" , 


"D5" 


"FINANCE" > 


"R9" 


"HOUSEKEEPING" t 


"X7" 


"GROUNDSKEEPING 


"R7" 


"BEEKEEPING" , 


ELSE "NOT A DEPARTMENT 


END-TABLE 


DTR> 





If you try to enter a department number that is not in the table, DATATRIEVE 
rejects the entry and prompts you for a correct one: 

DTR> READY PHONE HRITE(ret) 

DTR > STORE PH0NE(ret) 

Enter NAME: "BENJAMIN PAUL "(ret) 

Enter NUMBER: 75a87S9(RE]) 

Enter LOCATION: P0LE_S(ret) 

Enter DEPARTMENT: T4(ret) 

Validation error for DEPARTMENT 

Re-enter DEPARTMENT: T3(ret) 

DTR > 

12.4.2 Using the Keyword VIA with DATATRIEVE Tables 

To refer to tables in value expressions, combine the table name with the keyword 
VIA. DATATRIEVE compares the codes in the table with the value you supply. If 
the value matches one of the codes, DATATRIEVE uses the corresponding trans- 
lation in the table. Use the following format to refer to a dictionary table in a 
value expression: 

field-name 

*. prompt VIA table-name 

variable-name 
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You can refer to an entry in the dictionary table RIG_TABLE by using a prompt- 
ing value expression, as shown in the following PRINT statement: 

DTR> PRINT *."TYPE OF BOAT " VIA R I G_TABLE USING )<(30)(ret) 
Enter TYPE OF BOAT: KETCH© 
TWO MASTS t BIG ONE IN FRONT 

If you refer to a dictionary table in a PRINT statement, include an* edit string to 
specify the number of characters to be printed. If you omit the edit string, 
DATATRIEVE uses an edit string that is 10 characters long. 

12.5 DATATRIEVE Tables and Workspace 

Once you have referred to a table, it remains in your DATATRIEVE workspace 
until you either relinquish it with the RELEASE command or end your 
DATATRIEVE session. If you are redefining a table, you must release the old 
version before the new table takes effect. Note that DATATRIEVE does not 
release tables when you switch data dictionaries. 

You cannot have two tables with the same name in your workspace at the same 
time. Use the SHOW READY command to display the names of tables in your 
DATATRIEVE workspace. It is helpful for optimization to see the tables in your 
workspace so you can release tables you do not need. 

For a complete discussion of DATATRIEVE workspace, see Chapter 17 in this 
manual. 

1 2.6 Displaying Table Information 

You can use the SHOW TABLES command to list the names of all dictionary 
tables in your default dictionary. 

D T R > SHOW TABLES® 
Tables : 

DEPT-TABLE J0B_T I TLE NAME-TABLE RIG-TABLE 

DTR> 

12.6.1 Displaying Tables 

To display a dictionary table on your terminal, use the SHOW command and 
specify the name of the table. Use the following format to display a table: 



SHOW table-name 
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Here is an example: 



DTR > SHOW AREA_CODE_TABLE(ret) 

TABLE AREA-CODE_TABLE 

207 : MAINE* 

B03 : "NEW HAMPSHIRE" , 

802 : VERMONT » 

.617 : "EASTERN MASSACHUSETTS"* 

413 : "WESTERN MASSACHUSETTS" t 

401 : "RHODE ISLAND" t 

203 : CONNECTICUT* 

ELSE "NOT A VALID AREA CODE" 

END-TABLE 

DTR > 



12.6.2 Editing Tables 

You can modify a table in the current data dictionary with the DATATRIE VE 
Editor. Type EDIT and the table name, then use the Editor to make the desired 
changes. Remember to end a new table entry with a comma. When you EXIT 
from the Editor, DATATRIE VE places the modified table in your workspace. 

See Chapter 16 for more information on the DATATRIEVE Editor. 

The following example illustrates how to use the Editor to add a new entry to an 
existing table: 



DTR> SHOW NUM_L I ST(ret) 
TABLE NUM-LIST 
1 : "ONE" t 
2: "TWO" » 
3: "THREE" » 

ELSE "NUMBER OUT OF TABLE RANGE " 
END-TABLE 

DTR> EDIT NUM-LIST© 

E D > "ELSE "(ret) 

ELSE "NUMBER OUT OF TABLE RANGE " 
0ED> I (RET) 

IN> 4 : "FOUR" »(ret) 

1 N > - Z 
0ED> WHdjj 

1 : "ONE" t 
2: "TWO" t 
3: "THREE" t 
4 : "FOUR" t 

ELSE "NUMBER OUT OF TABLE RANGE" 
END-TABLE 

0ED> "Z 
DTR> 
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1 2.6.3 Deleting Tables 



You can delete a table from your current data dictionary with the DELETE com- 
mand. Use the following format: 

DELETE table-name [(P^>] 

The following example deletes AREA_CODE_TABLE from the default data 
dictionary: 

D T R > SHOW TABLES® 
Tables : 

AREA_CODE_TABLE JOB_T I TLE NAME-TABLE 
DTR> DELETE AREA_CODE_TABLE 5 (ret) 
D T R > SHOW TABLES(ret) 
Tables : 

JOB_TITLE NAME-TABLE 

DTR > 

12.7 Protecting Dictionary Tables 

When you create a dictionary table, DATATRIEVE stores its definition in the 
current data dictionary and creates an access control list (ACL) for it. 
DATATRIEVE automatically stores one project-programmer number (PPN) or 
user identification code (UIC) in the ACL with full access privileges. An account 
number is called a PPN under RSTS/E systems and a UIC under other operating 
systems. 

Your individual installation determines the actual PPN/UIC that is stored in the 
ACL. Any user logged in under that PPN/UIC and the creator of the table have 
R (Read), W (Write), E (Execute), M (Modify), and C (Control) access to the dic- 
tionary table. Depending on the PPN/UIC in the ACL, other users in the instal- 
lation may be able to delete, modify, or print the dictionary table. 

If you want to grant additional privileges to other users or further restrict the 
use of the dictionary table, you must modify its ACL. For more information 
on protecting dictionary tables and on modifying access control lists, refer to 
Chapter 19. 

To guard against accidental deletion of your dictionary table, you can maintain a 
backup copy of it by using the DATATRIEVE EXTRACT command to copy your 
table to a disk file or tape file. For example: 

DTR > EXTRACT ON NAMTAB . BK P NAME-TABLE© 
DTR > 
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Defining and Using Views 



A view is a special type of domain that lets you select some or all fields in some 
(or all) records from one or more domains. Using a view, you can refer to fields 
and field values in different domains without duplicating their records and data. 
You can use views to do the following: 

• Work with subsets of records 

• Refer to subsets of fields in records 

• Change the apparent order of the fields in records 

• Combine subsets of records from more than one domain 

• Modify the values in the fields you select 

A view does not actually change the way fields are organized in records or the 
way records are combined into data files. A view only changes how existing data 
appears to you. You can modify values in the fields selected by the view, but you 
cannot store or erase any records accessed by the view. 

A view is like a window in a house. Just as a window might let you look into 
more than one room, a view can let you look into more than one domain. A win- 
dow might give you a complete look at everything in one or more rooms, restrict 
what you can see to a few items of furniture, or only let you see the back of one 
chair. Similarly, a view can let you look at all records, a few records, or parts of 
records. 

Each window in a house gives you a different picture of what is inside, but the 
actual locations of the items you see are the same no matter how you look at 
them. In the same way, when you define a view, you do not affect the way infor- 
mation is actually stored. 
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13.1 Defining Views 



You define a view by creating a domain definition in your data dictionary with 
the DEFINE DOMAIN command: 

DEFINE DOMAIN view-name OF domain-name [,...] USING 

level-number-1 field-name-1 OCCURS FOR rse-1 . 

level-number-2 field-name-2 J 0CCURS F0R rse " 2 \ 

LFROM domain-name-2 J 



After the keyword OF, you must list each domain that the view uses. The 
domains you list cannot be views themselves. You may specify the domains in 
any order, separating them with commas. You must end each field definition 
with a period and end the view definition with a semicolon. 

You can use two clauses to define the fields in a view: 

• OCCURS FOR 

• FROM 

The top-level field must be denned with an OCCURS FOR clause. The record 
selection expression in the first OCCURS FOR clause determines the number of 
records in the view. Each subsequent OCCURS FOR clause creates a list within 
the view. Consequently, a view that contains more than one OCCURS FOR 
clause is always a hierarchy. (The first OCCURS FOR clause does not make the 
view a hierarchy. It only establishes the source record stream for the view.) 

See Chapter 14 for more information about hierarchies. 

You establish the fields of data for the view with the FROM clause. It specifies 
the name of the field and the domain from which it derives. The domain must be 
the same domain named in the preceding OCCURS FOR clause. The field name 
must be either a field name or a query name from that domain. 

If two or more fields have the same name, you might have to qualify those field 
names to avoid ambiguity. See Appendix A for more information about qualified 
field names. 



13-2 Defining and Using Views 



1 3.1 .1 Views Using Subsets of Records 



A view lets you work with a specific subset of records from another domain. For 
instance, you may want to work with the records for ketches only and no other 
rig type. The following example shows a view definition that allows you to work 
with four fields of the yachts that are ketches: 



DTR> DEFINE DOMAIN KETCHES© 
DFN> OF YACHTS USING© 

DFN> 01 KETCH OCCURS FOR YACHTS WITH RIG EO "KETCH " . (ret) 
DFN> 03 TYPE FROM YACHTS* (ret) 

DFN> 03 LOA FROM YACHTS. (ret) 

DFN> 03 PRICE FROM YACHTS. (ret) 

DFN> 5© 

DTR > READY KETCHES© 

DTR> PRINT FIRST 4 KETCHES© 



LENGTH 
OVER 

MANUFACTURER MODEL ALL PRICE 



ALBERG 37 MK II 37 $3G,951 

CHALLENGER 41 41 $51 ,228 

FISHER 30 30 

FISHER 37 37 



DTR > 



The view domain KETCHES, which is based on the single domain YACHTS, is 
not hierarchical because there is only one OCCURS FOR clause. 

You cannot store or erase records in a view. Otherwise, you can use a view just as 
you would any other domain. 



1 3.1 .2 Views Using Subsets of Fields 

Another type of view lets you refer to a subset of fields from the records of 
another domain. For example, the record definition for YACHTS contains seven 
elementary fields and three group fields: 



DTR > READY YACHTS© 
DTR > SHOW FIELDS© 
YACHTS 

BOAT 

TYPE [Indexed field] 

MANUFACTURER (BUILDER) [Character strinJt indexed Key] 

MODEL [Character strinSt indexed key] 
SPECIFICATIONS (SPECS) 

RIG [Character string] 

LENGTH_OUER_ALL (LOA) [Character string] 
DISPLACEMENT (DISP) [Number] 
BEAM [Number] 
PRICE [Number] 
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If you want to work with only a few fields of the record, you can create a record 
definition for those fields and then create a domain and a data file containing one 
record for each record in YACHTS. The result is a data file that duplicates some 
field values in an existing data file (YACHT.DAT). Maintaining these two files so 
that they always contain the same field values would be difficult. 

You can define a view, however, that lets you look at just the fields in YACHTS 
that you need without duplicating field values. You also avoid the additional 
time and overhead of creating another record definition and creating and updat- 
ing two data files: 

DTR > DEFINE DOMAIN MAKERS® 

DFN > OF YACHTS USING© 

DFN > 01 BOAT OCCURS FOR YACHTS* (ret) 

DFN > 03 TYPE FROM YACHTS* (ret) 

DFN > 03 RIG FROM YACHTS, (ret) 

DFN> 5 

DTR> READY MAKERS© 

DTR > PRINT FIRST G MAKERS© 

MANUFACTURER MODEL RIG 

ALBERG 37 MK II KETCH 

ALB I N 73 SLOOP 

ALB I N BALLAD SLOOP 

ALB I N VEGA SLOOP 

AMERICAN 2B SLOOP 

AMERICAN 2G-MS MS 

1 3.1 .3 Views Using More Than One Domain 

The preceding sections showed how to use view domains to define a subset of 
records or fields from a single domain. You can also use field values from more 
than one domain. 

The domain OWNERS, for example, contains records of yacht owners. Each 
record contains the owner's name and the name, builder, and model of the 
owner's yacht: 

DTR > SHOW OWNER-RECORD© 
RECORD OWNER-RECORD 
ALLOCATION IS LEFT-RIGHT 
01 OWNER . 

03 NAME PIC X(10) QUERY -HEADER IS " OWNER "/" NAME " 

ED I T_STR I NG IS X(5> . 
03 BOAT-NAME PIC X ( 1 7 ) QUERY -HEADER IS "BOAT NAME", 
03 TYPE. 

OS BUILDER PIC X( 10) , 

OG MODEL PIC X( 10) . 

5 

DTR> READY OWNERS© 

DTR> PRINT FIRST 1 OWNERS© 

OWNER 

NAME BOAT NAME BUILDER MODEL 

SHERM MILLENNIUM FALCON ALBERG 35 
DTR > 
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If you define a view that refers to both the OWNERS domain and the YACHTS 
domain, you can use any combination of fields and records in those domains. For 
example, you can include the name and yacht fields from the OWNERS domain 
and the price field from the YACHTS domain. 

The view SAILBOATS in the following example uses every field and every record 
in the YACHTS domain to match owners with the boats they own. It uses records 
from the OWNERS domain and matches those records by boat type with records 
in the YACHTS domain. It requests only the NAME field from those records. 

After the first OCCURS FOR clause, each OCCURS FOR creates a list within 
the view. A domain that contains a list is a hierarchy. The view SAILBOATS, 
therefore, is a hierarchical view: 



DTR> SHOW SAILBOATS© 
DOMAIN SAILBOATS 

OF YACHTS t OWNERS USING 
01 SAILBOAT OCCURS FOR YACHTS. 
03 BOAT FROM YACHTS. 

03 SKIPPERS OCCURS FOR OWNERS WITH TYPE EQ BOAT. TYPE. 
05 NAME FROM OWNERS. 

? 

D T R > 



The field SKIPPERS is a list of owner names. Each record in SAILBOATS can 
contain a NAME field for each of several owners. This view allows you to com- 
bine all the information on each yacht with the names of all its skippers. 

DTR> READY SAILBOATS© 

DTR> PRINT FIRST' 2 SAILBOATS WITH ANY SKIPPERS© 

LENGTH 

OVER OWNER 
MANUFACTURER MODEL RIG ALL WEIGHT BEAM PRICE NAME 



ALBIN 

C&:C 



MEGA KETCH 35 17*000 12 $33*000 STEVE 

HUGH 

CORVETTE SLOOP 31 8 »B50 01 JIM 

ANN 



DTR > 



Printing the values of list fields is illustrated later in this chapter. Hierarchies 
are discussed in greater detail in Chapter 14. 

In general, if you define a view that uses only one domain, use an OCCURS FOR 
clause to define the top-level field and then use FROM clauses to specify which 
fields the view contains. If you define a view using more than one domain, group 
the field definitions by the domain they refer to, putting the field definition with 
an OCCURS FOR clause first in each group. 
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1 3.2 Using a View Domain 



You use a view as you do any other domain. To ready a view, you must have R 
(Read) access privilege to the view, and you must also have the same access priv- 
ilege to each domain the view uses. You must have E (Execute) access privilege 
to the record definition associated with each domain. 

You cannot store or erase records in a view, but you can modify values of fields. 
For example, here is how to modify a field in the view KETCHES: 



DTR> READY KETCHES© 
DTR> SHOH KETCHES© 
DOMAIN KETCHES 

□F YACHTS USING 
01 KETCH OCCURS FOR YACHTS WITH RIG EQ "KETCH". 

03 TYPE FROM YACHTS. 

03 LOA FROM YACHTS. 

03 PRICE FROM YACHTS. 



D T R > READY KETCHES MODIFY© 

DTR> FIND KETCHES WITH PRICE EQ 0© 

C 4 records found] 

DTR> PRINT ALL© 



LENGTH 
OUER 

MANUFACTURER MODEL ALL PRICE 



FISHER 30 30 

FISHER 37 37 

PEARSON 3G5 3B 

PEARSON 413 42 



DTR> FOR CURRENT PRINT THEN MODIFY PR ICE© 



LENGTH 
OUER 

MANUFACTURER MODEL ALL PRICE 



FISHER 
Enter PRICE: 

FISHER 
Enter PRICE: 

PEARSON 
Enter PRICE: 

PEARSON 
Enter PRICE: 



30 

30000© 
37 

45000© 

3S5 

32000© 
413 

54000© 



30 
37 
36 
42 



D T R > PRINT ALL 



LENGTH 
OVER 

MANUFACTURER MODEL ALL PRICE 



FISHER 30 

FISHER 37 

PEARSON 365 

PEARSON 419 



30 $30 ,000 

37 $45,000 

3G $32 »000 

42 $54*000 



DTR> 
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1 3.2.1 Using a View That Contains a List 



To refer to field values contained in a list, use one of the methods described in 
Chapter 14. For example: 

DTR> SHOW SAILBOATS© 
DOMAIN SAILBOATS 

OF YACHTS* OWNERS USING 
01 SAILBOAT OCCURS FOR YACHTS. 
03 BOAT FROM YACHTS. 

03 SKIPPERS OCCURS FOR OWNERS WITH TYPE EO BOAT. TYPE. 
05 NAME FROM OWNERS. 

? 

DTR> READY SAILBOATS WRITE© 

DTR> FIND OWNED IN SAILBOATS WITH ANY SKIPPERS® 
C B records found] 

DTR> PRINT ALL© 

LENGTH 









OVER 








OWNER 


MANUFACTURER 


MODEL 


RIG 


ALL 


WEIGHT 


BEAM PRICE 


NAME 


ALBIN 


VEGA 


SLOOP 


27 


5 


»070 


08 $18 » 800 


STEVE 
















HUGH 


C&:C 


CORVETTE 


SLOOP 


31 


8 


,850 


09 


JIM 
















ANN 


ISLANDER 


BAHAMA 


SLOOP 


24 


a 


» 2 


08 $8 » 500 


JIM 
















ANN 
















STEVE 
















HARVE 


PEARSON 


10M 


SLOOP 


33 


12 


»44i 


1 1 


TOM 


PEARSON 


2S 


SLOOP 


2S 


5 


1 400 


08 


DICK 


RHODES 


SWIFTSURE 


SLOOP 


33 


14 


1 


10 


JOHN 



DTR> SELECT 3(H) 
DTR > FIND SKIPPERS© 
C 4 records found] 
DTR > PRINT ALL© 

OWNER 
NAME 

JIM 
ANN 
STEVE 
HARVE 

DTR> SELECT 2© 
DTR > MODIFY NAME© 
Enter NAME: ANNE© 

DTR > PRINT BOAT t ALL SKIPPERS SORTED BY NAME OF OWNED© 



(continued on next page) 
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MANUFACTURER 
ALB I N 

C&:C 

ISLANDER 



PEARSON 
PEARSON 
RHODES 



MODEL 
VEGA 

CORVETTE 
BAHAMA 



10M 
2G 

SWIFTSURE 



RIG 
SLOOP 
SLOOP 
SLOOP 



SLOOP 
SLOOP 
SLOOP 



LENGTH 
OVER 
ALL 

27 

31 

24 



33 
2G 
33 



WEIGHT BEAM PRICE 
5 »070 08 $ 1 8 »B00 
8fB50 OS 

4 »200 08 $B »500 



12 ,aai 

5 >400 
14 tO 



1 1 
08 
10 



OWNER 
NAME 

HUGH 

STEVE 

ANN 

JIM 

ANNE 

HARVE 

JIM 

STEVE 

TOM 

DICK 

JOHN 



DTR> 
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Using Hierarchies 




In DATATRIEVE, the term hierarchy refers to a one-to-many relationship 
between record sources. 

With hierarchies, you can nest record streams to see a single record from one 
record source displayed with a combination of records from another record 
source. This nesting established a parent-child relationship between the two 
record streams. For each record in the outer, parent record stream, you see all 
records in the inner, child record stream. Parent records are displayed even if 
there are no corresponding child records in the inner record stream. Some exam- 
ples of how this can be useful are: 

• One team with several players 

• One project with several workers 

• One employee with several previous jobs 

• One library with many books 

• One computer with several users 

Hierarchies let you define records with fields that are lists. Items in a list can 
contain more than one field, and the list itself may contain more than one item. 
Therefore, a list lets you store more than one value for a field or group of fields in 
one record. Lists are also called repeating fields. 

When you retrieve a value from a record containing a repeating field, you cannot 
always apply the same statements you do for other records. The following 
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sequence of statements shows what can happen when you try to print the repeat- 
ing field KIDS from the hierarchical record FAMILIES: 

DTR > READY FAMILIES© 
DTR > SHOW FAM I LY-REC© 
RECORD FAMILY _REC 
01 FAMILY, 

03 PARENTS* 

OS FATHER PIC )•(( 10) . 
OB MOTHER PIC X< 10) . 
03 NUMBER-K IDS PIC 39 EDIT-STRING IS Z9 . 

03 KIDS OCCURS TO 10 TIMES DEPENDING ON NUMBER-K I DS . 
OB EACH_K I D . 

09 K I D_NAME PIC X(10) QUERY -NAME IS KID. 
09 AGE PIC 99 EDIT-STRING IS Z9, 

5 



DTR > PRINT FATHER OF FAM I L I ES©) 

FATHER 

JIM 
JIM 



DTR > PRINT MOTHER OF FAMILIES© 

MOTHER 
ANN 

LOUISE 



DTR > PRINT KIDS OF F AM I L I ES© 

Expected end of statement t encountered "OF" 

DTR > 

You can print the names of fathers and mothers, but you get an error message 
when you try to print the list field KIDS. If you form a collection, you can again 
print information on fathers and mothers but not kids: 

DTR> FIND FAMILIES© 

C 1 3 records found] 

DTR> PRINT ALL FATHER© 

FATHER 

JIM 
JIM 



(continued on next page) 
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DTR> PRINT ALL MOTHER(ret) 



MOTHER 



ANN 

LOUISE 



DTR> PRINT ALL EACH_K I D(ret) 



Field "EACH_KID" is undefined or used out of context 
DTR > PRINT ALL KIDS© 

Field "KIDS" is undefined or used out of context 

DTR> PRINT ALL KIDS OF FAMILIES© 

Expected end of statement* encountered "OF" 

In the first two examples, you get a message stating that the field name is unde- 
fined or used out of context. The third example results in the same message you 
got in the previous example. To retrieve the information, you can apply one of 
the following methods to set up a DATATRIEVE context: 

• Use a FIND statement to establish a context for the list. Then use a SELECT 
statement to identify one record in the collection. 

• Use nested FOR RSE loops. The outer FOR loop forms a target stream of hier- 
archical records and the inner FOR loop forms a stream of list items within a 
hierarchical record. 

• Use inner print lists (ALL print-list OF rse) to form a stream of list items 
within a record stream. 

The following sections describe these methods for retrieving items from lists. For 
more information about DATATRIEVE context, see Appendix A in this manual. 



14.1 Retrieving Repeating Field Values with FIND and SELECT 
Statements 



You use the FIND statement to find all the records in the file that meet your 
specifications. Then you can use the SELECT statement to request any one of 
these records: 

DTR > READY FAMILIES® 
DTR > FIND FAMILIES© 
C 1 4 records found] 
DTR > SELECT 35 PRINT© 



FATHER 



MOTHER 



NUMBER 
KIDS 



KID 
NAME 



AGE 



JOHN 



JULIE 



ANN 
JEAN 



29 
2B 
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When you have selected a record that contains a list, you can treat the list as 
though it were a source of records like a domain or collection. You can continue 
as follows: 

DTR > PRINT KIDS© 
KID 

NAME AGE 

ANN 29 
JEAN 2B 
DTR > 

You can also combine the FIND and SELECT statements to single out one list 
item. Then the context of the selected list item allows you to use the list item 
name by itself in a PRINT statement. Continue the previous example by forming 
a collection of the KIDS list field and selecting a list item from the collection: 

DTR > FIND K I DS(retJ 

C 2 records found] 

DTR > SELECT 25 PRINT© 

KID 

NAME AGE 
JEAN 2G 
DTR> PRINT AGE© 
AGE 
2G 

DTR > 

14.2 Retrieving Repeating Field Values with Nested FOR Loops 

To retrieve values from list items by nesting FOR loops, start from the top of the 
hierarchy and work toward the list items you want to retrieve. In the following 
example, the source for the RSE in the first or outer FOR loop is the hierarchical 
domain FAMILIES. The source in the second loop is the list item KIDS: 

DTR > FOR FAMILIES© 
[Loo KinS for statement] 
CON> FDR KIDS WITH AGE < 10© 
[Looking for statement] 
C0N> PRINT KID_NAME© 

(continued on next page) 
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KID 
NAME 



URSULA 
RALPH 

CHRISTOPHR 

SCOTT 

BRIAN 

DAVID 

PATRICK 

SUZIE 

DTR> 

The FOR statement preceding the PRINT statement in the following example 
loops through all the records in FAMILIES. For each of those records, the RSE in 
the PRINT statement retrieves only the first kid whose age is less than 10: 

DTR> FDR FAMILIES© 
[Looking for statement] 

C0N> PRINT K I D_NAME OF FIRST 1 KIDS WITH AGE < 10(ret) 

KID 
NAME 

URSULA 

CHRISTOPHR 

SCOTT 

DAVID 

PATRICK 

DTR> 

The OF rse clause in the PRINT statement serves the same purpose as a nested 
FOR RSE statement. The inner RSE (FIRST 1 KIDS WITH AGE < 10) identifies 
items from the list field KIDS that are included with a FAMILIES record identi- 
fied by the outer FOR RSE statement. 

You get the same results using the following nested FOR rse statements: 

DTR > FOR FAMILIES FOR FIRST 1 KIDS WITH AGE < 10 PRINT K I D_NAME 



14.3 Retrieving Repeating Field Values with Inner Print Lists 



The simplest way to print a repeating field is to print the entire record contain- 
ing the repeating field: 

DTR > READY FAM I L I ES(retj 

DTR > PRINT FIRST 1 FAM I L I ESgET) 



FATHER 



MOTHER 



NUMBER 
KIDS 



KID 
NAME 



AGE 



JIM 



ANN 



URSULA 
RALPH 



7 
3 



dtr i^- 
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To print selected fields from the record, you must specify a print list in the 
PRINT statement. (Print lists consist of field names or other value expressions 
and modifiers.) To specify a list item in a print list, you must use an inner print 
list, which has the format: 

ALL print-list OF rse 

In the print list clause of the inner print list, include the list items you want to 
display. The OF rse of the inner print list creates a context for the item in the 
hierarchical list. 

You can nest an inner print list in a PRINT statement using any of the following 
formats. The arrows under each format show where the inner print list begins 
and ends. A sample PRINT statement for the FAMILIES domain illustrates each 
format: 

1. PRINT ALL ALL print-list OF rse OF rse 

t t 

DTR> PRINT ALL ALL K I D_NAME OF KIDS OF FIRST 1 FAMILIES® 

KID 
NAME 

URSULA 
RALPH 

DTR > 

2. PRINT [ALL] value-exp, ALL print-list OF rse OF rse 

t t 

D T R > PRINT ALL MOTHER t FATHER* ALL K I D-NAME 0F(ret) 
CON> FIRST 1 KIDS OF FIRST 1 FAMILIES® 

KID 

MOTHER FATHER NAME 

ANN JIM URSULA 

DTR > 

3. PRINT ALL ALL print-list OF rse, value-exp OF rse 

t t 

DTR > PRINT ALL ALL K I D_NAME OF FIRST 1 KIDS* FATHER OF (ret) 
CON> FIRST 1 FAM I L I E! 



KID 

NAME FATHER 
URSULA JIM 
DTR > 
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There are two important points to remember when working with inner print 
lists: 



• To DATATRIEVE, an inner print list is just another print list element in the 
outer print list. 

• An inner print list establishes context for items in a list. See Appendix A for 
more information about context. 

While inner print lists can complicate statements, they allow you to control com- 
pletely how DATATRIEVE displays repeating fields. By using the repeating field 
as the source for an RSE in an inner print list, you can specify which occurrences 
of the repeating field DATATRIEVE displays. 

As a rule of thumb, you can think of embedding an inner print list in a PRINT 
statement the same way you think of nesting parentheses in an arithmetic 
expression. Just as you put a matching left parenthesis for every right parenthe- 
sis in an arithmetic expression, there must be a matching ALL for every RSE in 
a PRINT statement. In the second format the first ALL is optional, but it is eas- 
ier to remember the rule of thumb than to remember when ALL is optional. 

The remainder of this section presents more examples to help you use inner print 
lists effectively. 

By limiting the RSEs in a PRINT statement, you can tailor a record stream to 
suit your needs. These next three examples show the results of limiting one or 
both of the RSEs in a PRINT statement that includes an inner print list using 
the second format: 



DTR> PRINT 


ALL MOTHER 


, ALI 




KID 




MOTHER 


NAME 


AGE 


ANN 


URSULA 


7 




RALPH 


3 


DTR> PRINT 


ALL MOTHER: 


t ALI 




KID 




MOTHER 


NAME 


AGE 


ANN 


URSULA 


7 


LOUISE 


ANNE 


31 


JULIE 


ANN 


23 


ELLEN 


CHRISTOPHR 





ANNE 


SCOTT 




SARAH 


DAM ID 





ANNE 


PATRICK 


a 


MERIDETH 


BEAU 


28 


DIDI 






RUTH 


ERIC 


32 


BETTY 


MARTHA 


30 


LOIS 


JEFF 


23 


SARAH 


CHARLIE 


31 


TRINITA 


ERIC 


IB 



(continued on next page) 
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DTR> PRINT ALL MOTHER » ALL EACH_K I D OF© 
CON> FIRST 1 KIDS OF FIRST 1 FAMILIES© 

KID 

MOTHER NAME AGE 

ANN URSULA 7 

DTR> 

If you want to display only items from the list field, you must precede the inner 
print list with two ALL keywords, one for each RSE you define. In the following 
examples, the first ALL matches the RSE, FIRST 1 FAMILIES WITH 
NUMBER_KIDS = 3. The second ALL matches the RSE, KIDS: 

DTR> PRINT ALL ALL EACH_K I D OF KIDS OF© 

[Looking for "FIRST"* domain name* or collection name] 

CON> FIRST 1 FAMILIES WITH NUMBER - KIDS = 3© 

KID 

NAME AGE 

JEFF 23 
FRED 2G 
LAURA 21 

DTR> PRINT ALL ALL K I D_NAME OF KIDS WITH© 
[Looking for Boolean expression] 
C0N> AGE GT 25 OF FAMILIES© 

KID 
NAME 



ANNE 

JIM 

ELLEN 

ANN 

JEAN 



BEAU 
BROOKS 

ERIC 

MARTHA 

TOM 

FRED 

CHARLIE 

HAROLD 

SARAH 



DTR > 

The last display contains blank lines that you would probably want to eliminate. 
Eliminating empty print lines is discussed in the next section. 
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Note that when you include a list field in a print list, you should specify the list 
field as the last item. The following example shows what happens when you spec- 
ify some other field after the list. The display of that field begins on the same line 
as the last item in the list: 

DTR> PRINT ALL ALL EACH_K I D OF KIDS, MOTHER OF FIRST 2 FAMILIES© 
KID 



NAME 


AGE 


URSULA 


7 


RALPH 


3 


ANNE 


31 


JIM 


20 


ELLEN 


26 


DAM ID 


2a 


ROBERT 


IB 


DTR > 





14.4 Retrieving List Items with Nested RSEs — Eliminating Empty Print 
Lines 

You can use Boolean expressions in the outer RSE to eliminate empty print 
lines. Empty print lines occur when the outer RSE includes records that do not 
satisfy the inner RSE. When DATATRIEVE processes a record that does not con- 
tain information needed by the inner RSE, it generates a carriage return and 
line feed. The following example illustrates empty print lines that result from an 
outer RSE (FAMILIES) that forces DATATRIEVE to include records that do not 
match inner RSE requirements: 

DTR > PRINT ALL ALL EACH_K I D OF KIDS NITH(rejj 
[Looking for Boolean expression] 
C0N> AGE GT 25 OF FAMILIES® 

KID 

NAME AGE 

ANNE 31 

JIM 29 

ELLEN 2S 

ANN 23 

JEAN 2S 



BEAU 


28 


BROOKS 


2B 


ERIC 


32 


MARTHA 


30 


TOM 


27 


FRED 


2G 


CHARLIE 


31 


HAROLD 


35 


SARAH 


27 



DTR > 
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In the following statement, the clause WITH ANY KIDS eliminates the blank 
line caused by the record of the family without children: 

DTR> PRINT ALL ALL EACH_K I D OF KIDS WITHES) 

[Looking for Boolean expression] 

CON> AGE GT 25 OF FAMILIES WITH ANY KIDS(ret) 



KID 

NAME AGE 

ANNE 31 

JIM 29 

ELLEN 2B 

ANN 29 

JEAN 2G 



BEAU 28 

BROOKS 2G 

ERIC 32 

MARTHA 30 

TOM 27 

FRED 2G 

CHARLIE 31 

HAROLD 35 

SARAH 27 



D T R > 

The four blank lines in the preceding print display represent the records of fami- 
lies who have kids, but whose kids have ages less than or equal to 25. The follow- 
ing statement excludes those records from the record stream and therefore 
eliminates the blank lines: 

DTR> PRINT ALL ALL EACH_K I D OF KIDS W I TH(ret) 
[Looking for Boolean expression] 

C0N> AGE GT 25 OF FAMILIES WITH ANY KIDS WITH© 
[Looking for Boolean expression] 
C0N> AGE GT 25(ret) 



KID 



NAME 


AGE 


ANNE 


31 


JIM 


29 


ELLEN 


2B 


ANN 


29 


JEAN 


2B 


BEAU 


28 


BROOKS 


2B 


ERIC 


32 


MARTHA 


30 


TOM 


27 


FRED 


2B 


CHARLIE 


31 


HAROLD 


35 


SARAH 


27 


DTR> 





14-10 Using Hierarchies 



You do not have to use an extra ALL before inner print lists if you put the PRINT 
statement in a FOR statement: 



DTR> FOR FAMILIES PRINT ALL EACH_K ID OF KIDS WITH(ret) 
CLooKind for Boolean expression] 
CON> K I D_NAME CONT " Y " (ret) 



KID 
NAME 



AGE 



JAY 

CISSY 

NANCY 



24 



DTR> 



1 4.5 Retrieving Values from Sublists 

You can use collections, nested FOR loops, or inner print lists to retrieve values 
from sublists (lists within lists). 

When you work with sublists, you must remember to create a context for each 
level of the hierarchy. The outermost context establishes the target record or tar- 
get record stream (source = FAMILIES); the second establishes the context for 
the list (source = KIDS); and the third establishes the context for the sublist 
(source = PET); and so on. 

This series of FIND and SELECT statements uses collections to retrieve one list 
item from PET: 

D T R > READY PETS© 

DTR> FIND PETS© 

C 3 records found] 

DTR> SELECT? FIND KIDS(ret) 

C 2 records found] 

D T R > SELECT! FIND PET(retj 

C 2 records found] 

DTR > SELECT; PRINT PET_NAME > PET_AGE(ret) 

PET PET 
NAME AGE 

POP 03 

DTR l^- 
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You can also use nested FOR loops for dealing with a sublist: 

DTR> FOR PETS NITH ANY KIDS© 

CLooKintf for statement] 

CON> FOR KIDS WITH ANY PET© 

[Looking for statement] 

CON> FOR PET WITH PET.AGE GT 0© 

[Looking for statement] 

CON> PRINT PET_NAME * PET_AGE© 



PET 


PET 


NAME 


AGE 


POP 


03 


SODA 


04 


MOUSE 


03 


SHORTY 


08 


SOUEEKY 


03 


FRANK 


07 


FRANK 


14 


DTR> 





You can also use inner print lists to get at all three levels of the hierarchy: 

DTR> PRINT ALL ALL ALL PET_NAME OF PET OF© 

CLooKinS for "FIRST"* domain name* or collection name] 

C0N> KIDS WITH ANY PET WITH PET-AGE NE OF© 

[Looking for "FIRST"* domain name* or collection name] 

C0N> PETS WITH ANY KIDS WITH ANY PET WITH PET_AGE NE 0© 

PET 
NAME 

POP 

SODA 

MOUSE 

SHORTY 

SOUEEKY 

FRANK 

FRANK 

DTR> 



14-12 Using Hierarchies 



Restructuring Domains 




This chapter describes how to create new domains with data from existing ones. 
You might do this to: 

• Add new fields to the record definition associated with the domain 
® Change field definitions to affect the values stored in the data file 

• Create a copy of a domain for testing 

• Change the file organization 

® Change the index structure (key fields) 

• Create a domain that contains a subset of records contained in another domain 

How you create the new domain depends on whether you want to keep the old 
domain. If you want to keep the old domain, follow these steps when creating the 
new domain: 

1. Define a new domain, its record, and its data file. 

2. Ready the new domain for WRITE or EXTEND access and the old domain 
for READ access. 

3. Use a statement with the following format to transfer field values from the 
old data file to the new one: 

FOR rse-FROM-old-domain-name 

STORE new-domain-name USING 

new-record-name = old-record-name 
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If you want to use old procedures on the new domain, you must edit them if they 
refer to fields not included in the new domain. See Chapter 9 for information 
about editing procedures. 

If the old procedures refer only to fields included in the new domain, you need 
not change the procedures. You can ready the new domain with the old domain 
name as an alias (READY NEW AS OLD) and execute the old procedures. 

If you do not want to keep the old domain, you can still use the old procedures if 
you follow these steps: 

1. Define the new domain (NEW), record (NEW_REC), and file (NEW.DAT). 

2. Use a statement with the following format to transfer the data from the old 
domain (OLD) to the new one (NEW): 

FOR rse-FROM-old-domain-name 

STORE new-domain-name USING 

new-record-name = old-record-name 

3. Use the REDEFINE command, which deletes the old domain and creates a 
new domain with the same name as the old domain. The new domain uses 
the old domain name (OLD), the new record definition (NEWREC), and the 
new data file (NEW.DAT): 

DTR> REDEFINE DOMAIN OLD USING NENREC ON NEN . DAT !(ret) 
DTR > 

4. Check the old procedures for any references to field names not included in 
the new record definition and edit where necessary. 

The following sections provide examples to help you restructure your own 
domains. 

15.1 A Sample Domain 

PROJECTS is a sample domain you can create to practice restructuring: 

DTR> SHOW PROJECTS t PRO JECTS_REC(ret) 
DOMAIN PROJECTS 

USING PROJECTS-REC ON PRO JEC .DAT 5 
RECORD PROJECTS_REC 

USING 
01 PROJECT, 

03 PROJ-CODE PIC 3(3) QUERY -NAME IS CODE, 

03 PRO J_NAME PIC X(10) QUERY -NAME IS NAME, 

03 MANAGER-NUM PIC 3(5) QUERY-NAME IS NUM, 

5 

DTR > 
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The data file PROJEC.DAT is a sequential file and contains these records: 

DTR> PRINT PROJECTS© 



PROJ PROJ MANAGER 

CODE NAME NUM 

002 GROUNDS 00006 

005 BUILDING 2 00003 

008 SHED 00002 

018 RESEARCH 00006 

037 PUB REL 00008 

073 MATERIALS 00002 



DTR> 



15.2 Changing Record and File Definitions and Using New Names 

This section shows you how to change record and file definitions using new 
names for the record and data file. 

To create a new domain with two fields added to PROJECTS_REC, follow these 
steps: 

1. Define a new domain: 



DTR > DEFINE DOMAIN NEW_ PRO JECTS(ret) 

DFN> USING NEW_PROJECTS_REC ON NWPROJ.DAT? (ret) 

DTR > 



2. Use the EXTRACT command to copy the old record definition to a command 
file: 



DTR> EXTRACT ON TEMP PRO JECTS_REC(retJ 
DTR> 



3. Exit DATATRIEVE and edit the command file TEMP.CMD. Remove the 
DELETE command from the first line of the file, change the name of the 
record, add the new fields, and include any other changes you want. 

4. Enter DATATRIEVE again and invoke the modified command file to enter 
the new record definition in the data dictionary: 



DTR> @TEMP(ret) 

DEFINE RECORD NEW-PRO JECTS-REC 
USING 



NEW 


-PROJECT. 






03 


PR0J_C0DE 


PIC 


3(3) QUERY-NAME IS CODE. 


03 


PRO J_NAME 


PIC 


X(10) QUERY-NAME IS NAME. 


03 


PROJ-COST 


PIC 


9(S)U99 EDIT-STRING IS $$$,$$9.99. 


03 


MANAGER-NUM 


PIC 


9(5) . 


03 


MANAGER-NAME 


PIC 


X ( 1 5 ) . 



[Record NEW-PRO JECTS-REC is 41 bytes Ion 3] 
DTR > 
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5. Define a data file for NEW-PROJECTS. This example creates an indexed 
file to replace the sequential file associated with PROJECTS: 



DTR> DEFINE FILE FOR NEM_ PRO JECTS K EY = C0DE(retj 
DTR > 



You are now ready to transfer the data from the old domain to the new one. 



15.2.1 Storing Data from All the Records in the Old Domain 

This section tells you how to transfer data from all the records in the old domain. 
The next section explains how to transfer data from a subset of the records in the 
old domain. 

You must first ready both domains. Ready the new domain for WRITE or 
EXTEND access and ready the old domain for READ access. Use the STORE 
statement in a FOR loop to transfer the data: 



DTR> READY NEW.PROJECTS NR I TE(ret) 
DTR> READY PRO JECTS(ret) 
DTR > FOR PROJECTS© 
[LooKinsf for statement] 
CON> STORE NEW-PROJECTS 
CLooKintf for assignment 
CON> NEW_PROJECTS_REC = 
DTR > 



USING® 
statement ( s ) ] 
PROJECTS_REC(ret) 



For each field name in NEW_PROJECTS_REC that matches a field name 
in PROJECTS_REC, the STORE statement transfers field values from 
the record in PROJECTS to a record in NEW-PROJECTS. If a field in 
NEW_PROJECTS_REC does not match a field in PROJECTS-REC, 
DATATRIEVE initializes the field according to its data type and field definition 
(zero for numeric fields; spaces for alphabetic and alphanumeric ones). 

The data file associated with NEW-PROJECTS now has records in it. When you 
display its contents on the terminal, you can see the values transferred from the 
PROJECTS domain, as well as initial values for the two new fields, PROJ-COST 
and MANAGER-NAME: 



DTR> PRINT NEW-PROJECTS© 



PROJ 
CODE 



PROJ 
NAME 



PROJ 
COST 



MANAGER 
NUM 



MANAGER 
NAME 



002 GROUNDS 

005 BUILDING 2 

008 SHED 

018 RESEARCH 

037 PUB REL 

073 MATERIALS 

DTR > 



$0 


00 


000 OS 


$0 


00 


3 


$0 


00 


00002 


$0 


00 


G 


$0 





8 


$0 





00002 
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1 5.2.2 Storing Data from a Subset of the Records in the Old Domain 

You can create the new domain from a subset of the old domain records. You 
specify the limiting conditions in the RSE following the FOR statement. For 
example, you could have limited NEW-PROJECTS to the projects of only two 
managers: 



DTR> FOR PROJECTS WITH MANAGER-NUM EQ 2i G(reTj 

C L o o K i n 3 for statement] 

CON> STORE NEW-PROJECTS USING© 

C L o o K i n 3 for assignment statement (s) ] 

CON> NEW_PROJECTS_REC = PRO JECTS_REC(ret) 

DTR> PRINT NEW-PROJECTS® 



PROJ 
CODE 



PROJ 
NAME 



PROJ 
COST 



MANAGER 
NUM 



MANAGER 
NAME 



2 
8 
018 
073 



GROUNDS 
SHED 

RESEARCH 
MATERIALS 



$ . S 

$ . 2 

$ . G 

$ . 2 



DTR> 



1 5.2.3 Deleting References to the Old Domain 

After you store records from the old domain in your new one, you can delete the 
old data file from your directory. You can continue to use your old procedures 
with the new record definition and data file, however, by using the REDEFINE 
command. As described earlier in this chapter, the REDEFINE command deletes 
the old domain and creates a new domain with the same name as the old domain. 
The domain is now defined with the new record definition and data file: 

DTR> REDEFINE DOMAIN PROJECTS USING® 
D F N > NEW_PROJECTS_REC ON NWPRO J ♦ DAT ? (ret) 
DTR> 

15.3 Changing Record and File Definitions and Using Old Names 

This section explains how to restructure domains when you do not want to access 
old data, but you want to keep the domain, record, and file names you created for 
the old domain. The sample statements use the domain PROJECTS. 

Using an alias is the easiest way to change data structures without changing the 
names you use for them. 

Note 

Notice that the changes made to the PROJECTS record and file 
definitions are not associated with the names you want until you 
use the FINISH command and ready the PROJECTS domain 
again. 
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The following list explains how to restructure domains. Steps preceded by 
(RSTS/E only) are necessary only if you are working on a RSTS/E system: 

1. (RSTS/E only) At the system command level, rename the data file associated 
with the domain you are restructuring. The examples in the following steps 
assume that PROJEC.DAT has been renamed OLDPRO.DAT. 

2. At the DATATRIEVE command level, use the EXTRACT command to copy 
the old record definition to a command file: 



DTR > EXTRACT ON TEMP PRO JECTS-REC© 
DTR > 



3. At the system command level, edit the command file TEMP.CMD to add the 
desired field definitions. Do not remove the DELETE command from the first 
line of the file. 

4. (RSTS/E only) At the DATATRIEVE command level, redefine the domain 
specifying the renamed data file: 



DTR > REDEFINE DOMAIN PROJECTS USING© 
DFN> PROJECTS_REC ON OLDPRO.DAT 5 (ret) 
DTR> 



5. At the DATATRIEVE command level, ready the domain as an alias: 



DTR> READY PROJECTS AS 0LD_PR0 JECTS© 
DTR > SHOW READY© 
Ready d o m a i n s : 

OLD_PROJECTS: RMS SEQUENTIAL » PROTECTED READ 

DTR > 



6. Invoke the modified command file to enter the revised record definition in 
the data dictionary: 



DTR > @TEMP© 






DELETE 


PRO JECTS-REC 5 






DEFINE 


RECORD PROJECTS. 


REC 




USING 








01 PROJECT, 






03 


PROJ-CODE 


PIC 


9(3) QUERY -NAME IS CODE, 


03 


PRO J-NAME 


PIC 


X(10) QUERY-NAME IS NAME, 


03 


PROJ-COST 


PIC 


9(GK>99 EDIT-STRING IS $$$ 


03 


MANAGER_NUM 


PIC 


9(5) . 


03 

5 


MANAGER-NAME 


PIC 


X ( 1 5 ) , 


[Record 


PROJECTS-REC is 


41 


bytes 1 o n ] 



DTR> 



7. (RSTS/E only) Redefine the domain PROJECTS using your original name 
for the data file: 



DTR > REDEFINE DOMAIN PROJECTS USING© 
DFN > PROJECTS_REC ON PRO JEC . DAT 5© 
DTR > 
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8. Define a new data file for the domain. When you ready a domain with an 
alias, as in Step 5, defining a new file does not interfere with the link 
between that readied domain and the file containing the old data. Do not use 
the SUPERSEDE option of the DEFINE FILE command. The following 
example changes the file organization from sequential to indexed: 

DTR > DEFINE FILE FOR PROJECTS KEY = NUM(ret) 
DTR> 

9. Ready the domain as a different alias and specify WRITE access mode. This 
READY command uses the new record definition and opens the new data file 
created by the DEFINE FILE command: 

DTR > READY PROJECTS AS NEW_PROJECTS WRITE© 

DTR > SHOW READY© 

Read y d oiiiai n s : 

NEN_PROJECTS: RMS INDEXED * PROTECTED WRITE 
OLD_PROJECTS: RMS SEQUENTIAL t PROTECTED READ 

DTR > 

10. Use the STORE statement in a FOR loop to move the data from the original 
domain to the new one. 

If you plan to use all the records in the domain, you simply specify the alias 
of the old domain in the FOR statement: 

DTR > FOR 0LD_PR0JECTS(ret) 

[LookinS for statement] 

C0N> STORE NEW_PR0JECTS USING© 

[Looking for assignment statement(s)] 

C0N> PROJECTS.REC = PROJECTS_REC@ED 

DTR> 

If you plan to use a subset of the records in the old domain, specify a more 
restrictive RSE including the alias of the old domain. The following example 
limits the record stream to the projects of two managers: 

DTR > FOR OLD-PROJECTS WITH MANAGER.NUM EQ 2t G@et) 

[Looking for statement] 

C0N> STORE NEW-PROJECTS USING© 

[Looking for assignment s t a t e m e n t ( s ) ] 

C0N> PR0JECTS_REC = PRO JECTS_REC(reT| 

DTR> 
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11. When you type FINISH and ready the domain again, you can access data as 
you restructured it. DATATRIEVE no longer recognizes either alias. The fol- 
lowing example assumes that the RSE specified in the FOR loop included all 
the records from the domain: 

DTR > FINISH© 
DTR> READY PROJECTS® 
DTR > SHOW READYdB 
Read v d omai n s : 

PROJECTS: RMS INDEXED t PROTECTED READ 
DTR> PRINT PROJECTS© 



PROJ 


PROJ 


PROJ 


MANAGER 


CODE 


NAME 


COST 


NUM 


2 


GROUNDS 


$0 . 


B 


5 


BUILDING 2 


$0 . 


3 


008 


SHED 


$0 . 


2 


018 


RESEARCH 


$0 . 


B 


037 


PUB REL 


$0 ♦ 


8 


073 


MATERIALS 


$ . 


2 



DTR> 

12. (RSTS/E only) At the system command level, delete the data file associated 
with your domain before you changed the file organization. Using the 
PROJECTS domain as an example, you would delete the file OLDPRO.DAT. 

1 5.4 Changing the Organization of a Data File 

You can also use an alias with the READY command to change only the organi- 
zation of a data file associated with a domain. 

The following steps make the indexed file created for PROJECTS a sequential 
file again: 

1. (RSTS/E only) At the system command level, rename the data file associated 
with PROJECTS. The examples in the following steps assume that 
PROJEC.DAT has been renamed IDXPRJ.DAT. 

2. (RSTS/E only) At the DATATRIEVE command level, redefine the 
PROJECTS domain specifying the renamed data file: 

DTR> REDEFINE DOMAIN PROJECTS USING© 
DFN> PROJECTS_REC ON IDXPRJ.DAT 5 (ret) 
DTR > 

3. Ready the domain using an alias: 

DTR > READY PROJECTS AS ID X - PROJECT S(ret) 
DTR> SHOW READY(ret) 
Read y d owai n s : 

IDX_PROJECTS: RMS INDEXED* PROTECTED READ 

DTR> 
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4. (RSTS/E only) Redefine PROJECTS again, using the original name of the 
data file: 

DTR> REDEFINE DOMAIN PROJECTS USING© 
DFN> PROJECTS_REC ON PRO JEC . DAT i©) 
DTR> 

5. Define for the domain a data file that has the organization you want. The 
following example defines a sequential file: 

DTR> DEFINE FILE FOR PROJECTS© 
DTR> 

6. Ready the domain for WRITE access using another alias: 

DTR> READY PROJECTS AS SE0_PR0JECTS WRITE© 
DTR > 

7. Using a STORE statement in a FOR loop, transfer records from the old 
domain to the new one: 

DTR> FOR IDX_PROJECTS© 

[Looking for statement] 

CON> STORE SEQ_PROJECTS USING© 

[Looking for assignment statement (s) ] 

CON> PROJECTS_REC = PRO JECTS_REC© 

DTR> 

8. Type FINISH. When you ready the domain again, access records in the reor- 
ganized file: 

DTR > FINISH© 
DTR > READY PROJECTS© 
DTR > SHON READY© 
Readied domains: 

PROJECTS: RMS SEQUENTIAL » PROTECTED READ 

DTR > 

9. (RSTS/E only) You may want to print some records to ensure that records 
were successfully copied to your reorganized file. Then, at the system com- 
mand level, delete the data file with the organization you no longer want. 
Using the PROJECTS domain as an example, you would delete 
IDXPRJ.DAT from your directory. 
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Using the DATATRIEVE Editor 




Using a command file is probably the easiest way to make changes to your 
DATATRIEVE work. You can edit a command file using the editor you already 
know from your own operating system, rather than learning a new editor. Chap- 
ter 10 explains how to use command files. The rest of this chapter explains how 
to use the DATATRIEVE Editor. 

You can use the DATATRIEVE Editor only to modify dictionary objects that are 
denned in your current data dictionary. You can edit commands and statements 
only when they are stored as a procedure. 

Edit with caution, especially when changing record definitions. The 
DATATRIEVE Editor does not check for syntax errors as you edit dictionary 
objects. Any errors show up only when you use the modified dictionary object. 

The changes you make with the DATATRIEVE Editor do not affect domains that 
you currently have readied in your workspace. For example, if you ready the 
domain PERSONNEL and then edit its record definition, you are not changing 
the record definition currently being used by the PERSONNEL domain. For the 
new record definition to take effect, you must finish the PERSONNEL domain 
and ready it again. Similarly, edits do not change a dictionary table loaded into 
your DATATRIEVE workspace until you release the table and refer to it again. 

1 6.1 Invoking the Editor 

You invoke the DATATRIEVE Editor at the DATATRIEVE command level with 
the following command: 

EDIT object-name [" (pa % Wd) l [ADVANCED] 
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Arguments 



object-name Is the name of the dictionary object in the current data diction- 
ary you want to edit. 

(passwd) Is an asterisk enclosed in parentheses (*) or the password neces- 

(*) sary to gain C (control) access to the dictionary object. If you 

specify a password, you must enclose it in parentheses. If you 
specify (*), DATATRIEVE prompts you for the password but 
does not print the response on your terminal. If you omit this 
argument, DATATRIEVE uses your login UIC/PPN to verify 
that you have C (control) access privilege to the dictionary 
object you want to edit. 

ADVANCED Must be included in the EDIT command if you want to edit a 
domain definition or a record definition. 



When you invoke the DATATRIEVE Editor, it responds with the QED> prompt. 



16.2 Editor Modes 



When you first invoke the Editor, you are at the Editor's command level in edit 
mode. In this mode, the Editor interprets all your input as commands, and you 
can display and alter the text of the dictionary object. The QED> prompt indi- 
cates that you are in edit mode. 

The second Editor mode, insert mode, allows you to enter text directly into the 
dictionary object. You enter insert mode with the INSERT and REPLACE com- 
mands and leave it by pressing CTRL/Z. The Editor uses the IN> prompt to indi- 
cate that you are in insert mode. In this mode, the Editor interprets all your 
input as new text to be entered into the dictionary object. 



16.3 Line Pointer 



Some commands move you through the text from one line to another. Other com- 
mands display or alter lines at various places in the text but leave the current 
line unchanged. The Editor uses a line pointer to keep track of the current line. 

The line pointer points to the entire current line, not to any part of the line. You 
can display the current line by typing a period (.) and pressing RETURN in 
response to the QED> prompt. The maximum line size you can edit is 132 
characters. 

The line pointer can also point to the end of the text buffer, where you can add 
text to the end of the dictionary object. The symbol [EOB] marks the end of the 
text buffer. 
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1 6.4 Range Specification 



The Editor commands for deleting, inserting, replacing, and typing lines, and for 
substituting strings all contain an optional argument that specifies the range of 
lines on which the command operates. The range may be a single line, a series of 
consecutive lines, or a group of nonsequential lines. For a complete listing of all 
the range specifiers you can use with the DATATRIEVE Editor, refer to the sec- 
tion on the EDIT command in the DATATRIEVE-1 1 Reference Manual Table 
16-1 shows several examples of these ranges using the TYPE command. TYPE 
displays specified lines on your terminal, and it searches for specified strings. 

If you want to display the rest of a dictionary object, the following commands all 
work: 

TYPE REST 

TYPE R 

REST 

T R 

IR 

Note the percent sign before the R in the last example. The Editor assumes R by 
itself is the abbreviated form of the REPLACE command. Entering R without 
the percent sign in response to the QED> prompt does not display the rest of the 
dictionary object; it deletes the current line and puts you in insert mode. 



Table 16-1 : Examples of Range Specifiers 



You Type: 


Editor Displays: 


TYPE 


ALL "BEAM" 


All lines containing the string BEAM. 


TYPE 


BEGIN AND END 


The first line of the dictionary object and the end-of-buffer 
marker ([EOB]). 


TYPE 


BEGIN t "BEAM" 


The first line of the dictionary object and the first line containing 
the string "BEAM". If the current line is the first line of the dic- 
tionary object and contains the string "BEAM", this command 
displays the current line twice. 


TYPE 


BEFORE 


All lines before the current line and the current line. 


TYPE 


BEGIN 


The first line of the dictionary object. 


TYPE 


END 


The end-of-buffer marker ([EOB]). 


TYPE 


. FOR 5 


The current line and the four lines following it. 


TYPE REST 


The current line and all remaining lines in the dictionary object. 


TYPE 


"BEAM" 


The next line containing the string "BEAM". If the current line 
contains "BEAM", the Editor displays the current line. 



(continued on next page) 
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Table 1 6-1 : Examples of Range Specifiers (Cont.) 



You Type: 


Editor Displays: 


TYPE WH 
TYPE BE + 5 
TYPE " BEAM " +G 

TYPE * 


All lines in the dictionary object. 

The sixth line of the dictionary object. 

The sixth line following the next line containing the string 
"BEAM". If the current line contains the string "BEAM", the 
Editor displays the sixth line following the current line. 

The current line. 



1 6.5 Editor Commands 

Table 16-2 summarizes the DATATRIEVE Editor commands in alphabetical 
order. The following section contains a sample editing session illustrating some 
common uses of these commands. 



Table 16-2: Summary of DATATRIEVE Editor Commands 



Command 


Format 


Function 


CTRL/Z 


CTRL/Z 


In edit mode, works like the EXIT command. In 
insert mode, returns control to edit mode. 


DELETE 


D[ELETE] [range] 


Deletes the specified range or the current line if 
you omit the range. After deletion, the current 
line is the line following the last line deleted. 


EXIT 


EX[IT] 


Returns you to DATATRIEVE command level. 
The edited dictionary object replaces the previous 
version in the data dictionary. 


INSERT 


l[NSERT] [range] 


Enters insert mode. The Editor inserts lines 
before the line specified by range or before the 
current line if you omit the range. CTRL/Z ends 
insert mode and returns you to the Editor com- 
mand level. If you omit the range, the current line 
does not change when you leave insert mode; if 
you specify a range, the line specified by the range 
becomes the current line. Do not use ALL, AND, a 
comma (,), BEFORE, FOR, a semicolon (;), REST, 
or WHOLE when specifying the range in this 
command. 


QUIT 


QUIT 


Returns you to DATATRIEVE command level and 
leaves the dictionary object unchanged by the 
editing session. 


REPLACE 


R[EPLACE] [range] 


Deletes the specified range or the current line if 
you omit the range and puts you in insert mode. 
CTRL/Z ends insert mode and returns you to the 
Editor command level. The current line is the line 
following the last line deleted. None of the restric- 
tions on specifying ranges in the INSERT com- 
mand apply to REPLACE. 



(continued on next page) 
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Table 16-2: Summary of DATATRIEVE Editor Commands (Cont.) 



Command 


Format 


Function 


SUBSTITUTE 


S/str-1/[str-2][/[range]] 


Substitutes string 2 for all occurrences of string 1 
in the specified range or in the current line if you 
omit the range. The line in which the last substi- 
tution occurred becomes the current line. If you 
omit the range, you can also omit the third delim- 
iter. If you omit string 2, the Editor deletes the 
specified string from the range you specify or from 
the current line if you omit the range. The search 
for the first occurrence of string 1 starts with the 
current line and proceeds toward the end of the 
text buffer. Do not use END to specify the range in 
this command. 


TYPE 


[T[YPE]] [range] 


Displays the specified range of lines or the line fol- 
lowing the current line if you omit the range. The 
first line displayed becomes the current line, with 
one exception: if E[ND] plays any part in the 
range of this command, the line pointer points at 
the end-of-buffer marker ([EOB]). 



16.5.1 DELETE Command 
Function 

Deletes one or more lines from the dictionary object. 
Format 

D[ELETE] [range] 

Argument 

range Specifies the range of lines to be deleted. If you omit the range, only the 
current line is deleted. 

Position of Line Pointer 

Current line is the line following the last line deleted. 
Examples 

Delete the current line only: 

0ED> D(RET) 

Delete all lines containing the string PHD: 

Q E D > D ALL "PHD "(RET) 
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Delete all lines containing the string "PHD" from the current line and the seven 
lines following it: 

QED> D "PHD" FOR 7(gH) 

Delete all lines from the beginning of the dictionary object up to and including 
the current line: 

E D > D BEFORE(RET) 

1 6.5.2 EXIT Command 
Function 

Ends an editing session, and returns you to DATATRIEVE command level. 
The edited dictionary object replaces the previous version in the data diction- 
ary. 

Format 

EX[IT] 
CTRL/Z 

Argument 

None. 

Position of the Line Pointer 

Not applicable. 
Examples 

End the current editing session with the EXIT command: 

OED> EX (RED 
DTR> 

End the current editing session with CTRL/Z: 

E D > "Z 
DTR > 

1 6.5.3 INSERT Command 
Function 

Enters insert mode, which allows you to enter text directly into the diction- 
ary object. The inserted lines are added before the line specified in the range 
or before the current line if you omit the range. 

Format 

l[NSERT] [range] 
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Argument 



range Is the line or group of lines that will follow the inserted lines. If you omit 
the range, DATATRIEVE adds the inserted lines before the current line. 

Position of the Line Pointer 

If you omit the range, the current line does not change when you leave insert 
mode. If you specify a range, the line that the range specifies becomes the cur- 
rent line. 

Notes 

• When you issue the INSERT command, the Editor prompts with IN> to show 
that you are in insert mode. 

• Remember to press RETURN after each line you want to insert. If you enter 
CTRL/Z after a line, that line is not entered into the procedure or table. In the 
following example, only the words READY YACHTS are inserted in the dic- 
tionary object: 

0ED> INSERTS 

IN> READY YACHTS(RET) 

IN> FIND TINIES IN YACHTS WITH LOA < 25 - Z 

0ED> 

• Do not use the following range specifiers in the INSERT command: 

- [%]ALL 

- [%]AND(,) 

- [%]BEFORE 

- [%]FOR(;) 

- [%]R[EST] 

- [%]WH[OLE] 

• To leave insert mode and return to edit mode, enter CTRL/Z. 

Examples 

Insert lines before the current line: 

0ED> I (RET) 

IN> READY YACHTS(RET) 



IN> PRINT ALL T I N I ES(RET) 

I N > ■ • Z 

0ED> 
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Insert lines before the first line of the dictionary object: 

E D > I BEG I N(RET) 

IN> READY YACHTS(RET) 

Insert lines after the last line of the dictionary object: 

OED> I ENDfREp 
C EOB ] 

IN> PRINT ALL T I N I ES(RET) 

Insert lines before the next line containing the string "BEAM": 

QED> I ' BEAN '(RET) 

IN> PRINT ALL TINIES SORTED BY BEAM(R|T) 

Insert lines between the fourth and fifth lines from the current line: 

E D > I . +5(REp 

IN> PRINT BUILDER OF TINIES(RET) 

1 6.5.4 QUIT Command 
Function 

Returns you to the DATATRIEVE command level and leaves the dictionary 
object unchanged by the editing session. 

Format 

QUIT 

Argument 

None. 

Position of the Line Pointer 

Not applicable. 
Notes 

• QUIT aborts an editing session. Any changes made during the session do not 
affect the dictionary object. 

• You cannot abbreviate the QUIT command. 
Example 

Abort the current editing session: 

QED> QUI TfRET) 
D T R > 
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16.5.5 REPLACE Command 
Function 

Deletes the specified range of lines in a dictionary object or deletes the cur- 
rent line if you omit the range and enters insert mode, which allows you to 
enter text directly into the dictionary object. 

Format 

R[EPLACE] [range] 

Argument 

range Specifies the range of lines to be deleted. If you omit the range, 
DATATRIEVE deletes only the current line. 

Position of the Line Pointer 

After you leave insert mode, the current line is the line following the last line 
deleted. If you have inserted lines, the current line is the line after the inserted 
lines. 

Notes 

• When you issue the REPLACE command, the Editor deletes the lines you 
specify in the range and then prompts with IN> to show that you are in insert 
mode. 

• To leave insert mode and return to edit mode, enter CTRL/Z. 

« The restrictions on specifying ranges in the INSERT command do not apply to 
REPLACE. 

Examples 

Replace the current line with a single line: 

E D > FIND YACHTS WITH LOA BETWEEN 3G AND 37(REp 
OED> R(RED 

IN> FIND YACHTS WITH LOA > 38® 

1 N > " Z 
OED> .(HIS 

REPORT CURRENT SORTED BY BEAM * LOA » RIG ON . WHERE 

Delete the first line of a dictionary object and enter insert mode: 

OED> R BEfRET) 
I N > 

Delete all lines containing the string "PRICE" and enter insert mode at the line 
following the last line deleted: 

OED> R ALL "PRICE"(RH) 
I N > 
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Delete all lines in the dictionary object and enter insert mode: 

OED > R WH0LE(RET) 
I N > 

16.5.6 SUBSTITUTE Command 



Function 

Substitutes a character string for all instances of another character string in 
the specified range or in the current line if you omit the range. 

Format 

SUBSTITUTE] /string-1 /[string-2][/[range]] 

Arguments 

string-1 Is the string of characters to be replaced. 

/ Is the delimiter that separates string 1, string 2, and the range. The 

delimiter can be any printing character not in string 1 or string 2. In 
any given SUBSTITUTE command, you must use the same character 
as a delimiter. You need only specify the first two delimiters if you 
omit the range. 

string-2 Is the string of characters to replace string 1. If you omit string 2, then 
string 1 is deleted from the specified line. 

range Specifies the range of lines within which D ATATRIE VE will make the 
substitution. If you specify a range, DATATRIEVE replaces all occur- 
rences of string 1 in that range with string 2. If you omit the range, 
DATATRIEVE replaces only the first occurrence of string 1. That first 
occurrence of string 1 need not be in the current line. 

Position of the Line Pointer 

If a substitution takes place, the current line is the last line in which the substi- 
tution occurred. If there is no match for string 1 within the range, or if there is 
no match for it in the current line or any line from that point to the end of the 
dictionary object, no substitution takes place. The current line remains 
unchanged. 

Notes 



• The Editor prints each line in which a substitution occurs. 

• Do not use END to specify the range in this command. 

• The search for the first occurrence of string 1 starts with the current line and 
moves toward the end of the text buffer. 
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Examples 

Substitute the string YACHT for the first occurrence of the string YAHCT in the 
current line only: 

QED> S /YAHCT/YACHT/ ♦ (RET) 

Substitute the string YACHT for every occurrence of YAHCT in the entire dic- 
tionary object: 

QED>S *YAHCT*YACHT* WH(HD 

This WHOLE range is in effect regardless of the current line's position in the 
text buffer. Substitute the string YACHT for the next occurrence of YAHCT: 

E D > S /YAHCT/YACHT 

If there is no occurrence of string 1 between the current line and the end of the 
text buffer, then DATATRIEVE does not change the current line. 

Substitute the string YACHT for every occurrence of YAHCT from the current 
line to the end of the dictionary object: 

E D > S "YAHCT" YACHT" REST(RET) 

16.5.7 TYPE Command 
Function 

Displays the specified range of lines or the line following the current line if 
you omit the range. 

Format 

[T[YPE]] [range] 

Argument 

range Specifies the range of lines to be displayed. If you omit the range, the 
Editor displays only the line following the current line. 

Position of the Line Pointer 

The first line displayed becomes the current line, with one exception. If the range 
of this command contains E[ND], the line pointer points to the end-of-buffer 
marker ([EOB]). 
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Notes 

• Both the command name and range are optional. If you press the RETURN 
key, the Editor prints the line following the current line, which then becomes 
the current line. You can also enter the range specifiers without the command 
name. 

• The TYPE command performs the searches in the DATATRIEVE Editor. You 
can search for text strings in dictionary objects by enclosing the string you 
seek in pairs of single or double quotation marks. 

Examples 

The following commands all work as alternative ways of displaying lines during 
an editing sessionr 

Commands for displaying the current line only: 

QED> TYPE .(RET) 
OED> « (RET) 

Commands for displaying the next line (the line following the current line): 

QED> TYPE ♦ + lfRET) 
E D > . + 1(RET) 
0ED> T(RET) 
E D > (RH) 

Commands for displaying the entire dictionary object: 

E D > T WH(RET) 
OED> WH(RET) 

Commands for displaying the first and last lines of the dictionary object: 

E D > T BEGIN >END(RET) 
E D > BEGIN ,END(RD 
QED > BE AND E(RET) 

Commands for displaying all lines from the current line to the end of the diction- 
ary object: 

QED> T RESTfRET) 
QED > REST(RET) 
E D > ZRfREp 
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1 6.6 Sample Editing Session 



DTR> EDIT CTRL(RH) 
QED> WH(HT) 

READY YACHTS 

FIND YACHTS NITH LOA BETWEEN 3G AND 37 

REPORT CURRENT SORTED BY BEAM » LOA * RIG ON ♦WHERE 

SET REPORT-NAME = "YACHTS WITH LENGTH-OMER- ALL " / 

"OF 3B AND 37 FEET" 
AT TOP OF BEAM PRINT COL 1* "BEAM = " * COL 7* BEAM 
AT TOP OF LOA PRINT COL 12* "LENGTH = "* COL 20 * LOA » SKIP 
PRINT BUILDER* RIG* DISP 

AT BOTTOM OF RIG PRINT SKIP* COL 4* "NUMBER OF "* COL 14* 
LOA(" " )* COL 17* "FOOT "> COL 22* RIG* COL 28* 
"WITH BEAM OF "» COL 40* BEAM* COL 43* " = "* COL 4G * 
COUNT USING 23 » SKIP 

AT BOTTOM OF REPORT PRINT SKIP* "LIGHTEST = " » MIN (DISP)* 
SKIP* "HEAVIEST = "* MAX (DISP)* SKIP* 
"AVERAGE WEIGHT OF ALL BOATS = "* AVERAGE (DISP) 

SET DATE = "DD-MMM-YY" 

SET COLUMNS-PAGE = GO 

END-REPORT 
E D > ♦(RET) 

READY YACHTS 

E D > (RET) 

FIND YACHTS WITH LOA BETWEEN 3G AND 37 
E D > RfREp 

IN> FIND YACHTS WITH LOA > 38(15 

IN> "Z 
OED> ♦ (RET) 

REPORT CURRENT SORTED BY BEAM* LOA* RIG ON ♦ WHERE 
Q E D > S/ON .WHERE/(RH) 

REPORT CURRENT SORTED BY BEAM* LOA* RIG 

E D > (H) 

SET REPORT-NAME = "YACHTS WITH LENGTH-OVER-ALL"/ 

OED> (BE) 

"OF 3G AND 37 FEET" 

OED> R(RET) 

IN> "GREATER THAN 38 FEET "(RET) 

I N > - Z 

E D > ♦ (RET) 

AT TOP OF BEAM PRINT COL 1* "BEAM = "» COL 7* BEAM 

E D > ALL "AT BOTTOM "(REp 

AT BOTTOM OF RIG PRINT SKIP* COL 4* "NUMBER OF "* COL 14* 
AT BOTTOM OF REPORT PRINT SKIP* "LIGHTEST = "» MIN (DISP)* 

QED> ♦ (RH) 

AT BOTTOM OF RIG PRINT SKIP* COL 4* "NUMBER OF " » COL 14* 
OED> "BOTTOM "(RET) 

AT BOTTOM OF RIG PRINT SKIP* COL 4* "NUMBER OF "* COL 14* 

OED> (RED 

LOA(" ")* COL 17* "FOOT "* COL 22* RIG* COL 28* 
Q E D > "BOTTOM"(Rll) 

AT BOTTOM OF REPORT PRINT SKIP* "LIGHTEST = "* MIN (DISP)* 
OED> . ;3(RET) 

AT BOTTOM OF REPORT PRINT SKIP* "LIGHTEST = "* MIN (DISP)* 
SKIP* "HEAVIEST = " » MAX (DISP)* SKIP * 
"AVERAGE WEIGHT OF ALL BOATS = " > AVERAGE (DISP) 

OED> ♦ (RET) 

AT BOTTOM OF REPORT PRINT SKIP* "LIGHTEST = "» MIN (DISP)* 
E D > D ♦ ;3(REp 
OED> ♦ (RET) 

SET DATE = "DD-MMM-YY" 



(continued on next page) 
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OED> I (RET) 

IN> SET MAX- PAGES = 40 (RET) 

IN> -Z 
0ED> » (RET) 

SET DATE = "DD-MMM-YY" 

0ED> (RET) 

SET COLUMNS-PAGE = GO 

OED> (reT) 

END-REPORT 

OED> (RET) 

CEOB] 
OED> BE(RET) 

READY YACHTS 
OED> S/RIG/PRICE/WH(RET) 

REPORT CURRENT SORTED BY BEAM > LOA , PRICE 

PRINT BUILDER, PRICE, DISP 

AT BOTTOM OF PRICE PRINT SKIP, COL 4, "NUMBER OF ", COL 14, 
LOA(" "), COL 17, "FOOT ", COL 22, PRICE, COL 28, 

OED> WH(HD 

READY YACHTS 

FIND YACHTS WITH LOA > 38 

REPORT CURRENT SORTED BY BEAM, LOA, PRICE 

SET REPORT-NAME = "YACHTS WITH LENGTH_OOER_ALL"/ 

"GREATER THAN 38 FEET" 

AT TOP OF BEAM PRINT COL 1, "BEAM = " , COL 7, BEAM 

AT TOP OF LOA PRINT COL 12, "LENGTH = ", COL 20, LOA, SKIP 

PRINT BUILDER, PRICE, DISP 

AT BOTTOM OF PRICE PRINT SKIP, COL 4, " NUMBER OF ", COL 14, 
LOA(" "), COL 17, "FOOT ", COL 22, PRICE, COL 28, 
"WITH BEAM OF ", COL 40, BEAM, COL 43, " = ", COL 46, 
COUNT USING Z9 , SKIP 
SET MAX -PAGES = 40 
SET DATE = "DD-MMM-YY" 
SET COLUMNS-PAGE = BO 
END-REPORT 
OED> EX (RET) 
DTR> 
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Optimizing Workspace and Response Time 



This chapter explains the concept of DATATRIEVE workspace. It shows you how 
to use memory space efficiently during a DATATRIEVE session and suggests 
ways to optimize DATATRIEVE performance. 

17.1 Using Workspace 

Your DATATRIEVE workspace is the area in physical memory that is available 
to you during your DATATRIEVE session. Sometimes referred to as "pool space," 
the workspace is not the same as disk space. Workspace refers instead to the 
size of the current DATATRIEVE task you are performing. The maximum work- 
space allowed for each DATATRIEVE session is 32K words. If the task you per- 
form requires DATATRIEVE to use more than 32K words of memory, you receive 
an error message, such as "Compiler storage pool exhausted," and are unable to 
complete your task. 

1 7.2 Effect of READY and FINISH on Workspace 

Before you ready any domains, the workspace looks like that in Figure 17-1. All 
the workspace is available, some of it for carrying out tasks related to Record 
Management Services (RMS), some for tasks related to DATATRIEVE domains, 
and some for sorting the records as you issue DATATRIEVE commands and 
statements. 
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RMS WORKSPACE 



SORT WORKSPACE 



SMALL BLOCK WORKSPACE 



Figure 17-1 : Empty DATATRIEVE Workspace 



The dashed lines indicate temporary boundaries. DATATRIEVE takes space 
from the sort workspace and allocates it to the RMS workspace and the small 
block workspace when they need more space. A readied domain uses space in 
both the RMS workspace and the small block workspace. Collections, variables, 
and tables all use space in the small block workspace. 

If you use the SHOW SPACE command, you see that the proportions of space 
used are comparable to those in the diagram. The numbers you see for your sys- 
tem will not be identical with those in the following example: 



DTR > SHOW SPACE(RET) 



RMS pool 

Small b 1 o c K pool 
Sort pool 
Total 



***Cu r rent 
Allocated 
4384 
312 
14024 
18720 



Memory UsaSe*** 



Used 
4148 



44G0 



Free 
238 


14024 
142B0 



of Fragments 
3 


3 



When using the SHOW SPACE command, pay particular attention to the total 
used space and the total free space. As you take up more workspace, the used 
space increases and free space decreases. 

When you ready a domain, you begin to use up the available workspace, as 
shown in Figure 17-2. 
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YACHTS BUFFERS 



FREE SORT WORKSPACE 



YACHTS BLOCKS 



Figure 17-2: Workspace with One Readied Domain 



If you type SHOW SPACE, you can see how the values change for current use of 
memory: 

DTR> READY YACHTS®) 
DTR > SHOW SPACEdD 

#**Current Memory Usatfe*** 





Allocated 


Used 


Free 


# of 


RMS pool 


4384 


4282 


220 


1 


Small b 1 o c K pool 


2300 


1588 


712 


15 


Sort pool 


1203G 





12038 





Total 


18720 


5880 


12840 


IB 



If you ready a second domain, you use additional space as shown in Figure 17-3. 



YACHTS BUFFERS 



PERSONNEL BUFFERS 



FREE SORT WORKSPACE 



PERSONNEL BLOCKS 



YACHTS BLOCKS 



Figure 17-3: Workspace with Two Readied Domains 



Type SHOW SPACE to see values for current memory use after readying two 
domains: 

DTR > READY PERSONNEL^ 
DTR> SHON SPACE(RET) 
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***Current Memory UsaSe*** 





Allocated 


Used 


Free 


* of 


RMS pool 




4388 


220 


5 


Small b 1 o c K pool 


341B 


2B5S 


7G0 


21 


Sort pool 


103B0 





103G0 





Total 


18720 


7044 


1 1G7B 


2B 



If you finish a domain, you free the workspace that the domain was occupying. 
The sort workspace recovers free space only if the free space is adjacent to the 
sort workspace. If you free space in the interior of the RMS workspace or small 
block workspace, then it remains in that workspace as a fragment, as shown in 
Figure 17^. 



FREE RMS WORKSPACE 



PERSONNEL BUFFERS 



FREE SORT WORKSPACE 



PERSONNEL BLOCKS 



FREE SMALL BLOCK WORKSPACE 



Figure 17-4: Workspace When You Finish First Readied Domain 

The following SHOW SPACE command illustrates that releasing the first read- 
ied domain does not increase the amount of free sort workspace: 

DTR> FINISH YACHTS(RET) 
DTR > SHOW SPACE(RET) 

***Current Memory UsaSe*** 





Allocated 


Used 


Free 


# of 


RMS pool 


4944 


4244 


7 


5 


Small block pool 


341G 


1380 


203B 


12 


Sort pool 


103G0 





103B0 





Total 


18720 


5B24 


1309B 


17 



DTR> 

You use the sort workspace each time you specify the order of a record stream 
with the SORTED BY clause in an RSE or a collection with the SORT statement. 
DATATRIEVE immediately seizes space from the sort workspace and releases it 
when it finishes the sort. DATATRIEVE sorts slowly when it has little space to 
work with, so keeping the sort workspace as large as possible saves computing 
time. If the sort workspace is too small, DATATRIEVE returns the message: 

Sort workspace exhausted 
Execution failed 
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1 7.3 Techniques to Optimize Workspace 



The following techniques for readying and finishing domains can help you opti- 
mize your workspace: 

• Try to reduce the number of files you have open at a time. If you no longer need 
a domain, FINISH it. 

• Pay attention to the order in which you open the files. As the illustrations 
show, when you finish a domain you do not always free a complete, contiguous 
block of workspace. If you finish the first domain before you finish the second, 
your workspace looks like that in Figure 17-4. It is best, therefore, first to 
ready the domains you plan to use the longest and then ready and finish those 
you need for only a short time. 

You can save space in the way you define your records too. Each time you define 
a field, you add overhead cost in addition to the size of the item being stored. 
EDIT-STRINGS, QUERY-HEADERS, and QUERY-NAMES also add to the stor- 
age space your record requires. Use the following guidelines when defining your 
record: 

• Keep record definition clauses short, in particular EDIT-STRINGS, QUERY- 
HEADERS, and QUERY-NAMES. Do not use any of these clauses 
unnecessarily. 

• Use short names and eliminate unnecessary fields. Unnecessary group fields 
are a particular waste of space. 

• When you use FILLER, try to combine two or more elementary fields into one 
FILLER field. 

There are also other techniques you can use to save space: 

• Release collections, tables, and variables that you do not need. 

• Avoid using long BEGIN-END blocks, and the THEN connector to form com- 
pound statements. DATATRIEVE compiles the complete statement all at once, 
at the cost of workspace. 

• Use a small file bucket size. The file bucket size determines the size of the 
RMS buffers needed. A bucket size of 8 would use approximately half of 
DATATRIEVE workspace and would cause you to run out of space repeatedly. 
A bucket size of 1 or 2 reduces the requirements for DATATRIEVE workspace. 

• For the REPORT statement, first use the FIND statement to form a collection 
and the SORT statement to sort and then report on the sorted collection. Avoid 
including the SORTED BY clause in the REPORT statement. The REPORT 
and SORT statements both require large amounts of workspace. 
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1 7.4 Techniques to Optimize Response Time 



As mentioned earlier, DATATRIEVE performs best when it has adequate space 
to work with. Therefore, when you keep the sort pool in your workspace as large 
as possible, you improve response time. The following sections suggest other 
ways you can improve DATATRIEVE performance. 

1 7.4.1 Using the ALLOCATION Option of the DEFINE FILE Command 

If you know approximately how many blocks of storage your data file will 
require and you want to enter records quickly, you can use the ALLOCATION 
option in the DEFINE FILE command to reserve contiguous storage space for 
the file. This option is particularly useful if you know your data file will be large. 
The format for the ALLOCATION option is ALLOCATION = n, where n is the 
number of blocks you want as the initial allocation for the file. 

17.4.2 Using Keyed Access Efficiently 

DATATRIEVE allows you to define indexed or sequential files for your data. 
Sequential files require less storage, but DATATRIEVE must search records one 
by one according to their physical order in the file. This organization may be 
optimal in certain cases. For example, a domain's records may contain a field for 
the current date, so you may want records physically arranged in the order in 
which you stored them. For instance, you are likely to want to have sequential 
access to banking transactions. If you access groups of records in chronological 
order, you might find sequential organization efficient. 

In other cases, your access needs may not be suited to sequential organization. 
You may need to access a group of records that are distributed throughout the 
file. If you have stored the records in a sequential file, DATATRIEVE may have 
to read all the records to find the one or two that you request. In this case, 
indexed file organization is probably a better choice. Although indexed files 
require more storage, DATATRIEVE can search indexed files quickly to find the 
records you want, if you base the search on a key field. 

When defining data, try to decide which field of the record you are likely to name 
most often in queries. Make that field the primary key if its value is likely to be 
unique for each record. For example, if you are setting up a personnel domain, 
you might predict that most users seek information based on employee ID. In 
that case, make the ID field the primary key. 

By default, primary key values are unique. That is, the primary key value by 
itself is enough to identify a record. It is legal in DATATRIEVE to specify that 
primary keys can have duplicate values. However, allowing duplicate primary 
key values is not recommended; having too many duplicate key values slows 
DATATRIEVE searches based on key fields. 
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If the leading candidate for the primary key does not uniquely identify the 
record, find another field such that the two fields combined can uniquely identify 
the record. You can then designate a group field, encompassing the two fields, as 
the primary key. For example, in the YACHTS domain, the group field TYPE 
(consisting of BUILDER and MODEL) is the primary key, uniquely determining 
records in YACHTS. 

After organizing your indexed file and storing records in the file, you should 
structure DATATRIEVE queries to take advantage of keyed access. A query is a 
request for DATATRIEVE to identify all the records that satisfy a specified con- 
dition. Not all the DATATRIEVE queries you can formulate use keyed access to 
indexed files. The following sections tell you how to produce queries that give 
you the fastest response time. 

Avoid using a field defined as USAGE IS DATE as a key field. The value stored 
in a date field is larger than the maximum value allowed for a key by RMS. 
Therefore, specifying a date field as a key provides no response time advantage 
when you base a query on a comparison of the field value and the range of values 
(for example, LT, GT, LE, GE, and BETWEEN). If you base your query of an 
indexed data field on an equality comparison, DATATRIEVE uses the index and 
performs faster than if it did a sequential search of the records. 

17.4.2.1 Using EQUAL Rather Than CONTAINING — A Boolean expression that 
tests records with the EQUAL ( = ) relational operator is more efficient than a 
Boolean with CONTAINING (CONT) when the expression refers to a key field. 
For example, compare these two queries: 

DTR> PRINT YACHTS WITH BUILDER = " PEARSON "(RET) 

D T R > PRINT YACHTS WITH BUILDER CONT " PEARSON "(RET) 

Although both queries yield the same results, the first query is twice as fast as 
the second one. 

To resolve the first query, DATATRIEVE conducts a fast search through the 
index to retrieve the desired records. In the second case, DATATRIEVE must 
search through the values of BUILDER looking for matches with the string fol- 
lowing CONT. DATATRIEVE must check all substrings of each BUILDER value 
that are equal in length to the string specified in the Boolean. 

To take advantage of the increased efficiency of EQUAL ( = ), you must specify a 
value that matches the field value exactly. EQUAL ( = ) is case sensitive but 
CONT is not. In the last example, if a record had the value "Pearson" for 
BUILDER, only the second query would find the record. 

To get around the problem of case sensitivity, you might consider using only 
uppercase letters when entering data. Otherwise, to use the EQUAL operator, 
you must remember the case of each character of a field value. 
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17.4.2.2 Choosing Domains or Collections as Record Sources — When you form a 
collection, DATATRIEVE can no longer use key-based access for retrieving 
records. In most cases, you get the best performance on key-based queries when 
you specify a domain rather than a collection in the RSE. 

Furthermore, if you form a query that relates to more than one record source, all 
but the last source specified is an implied collection. Therefore, you cannot have 
key-based access for any but the last record source in a relational query. When 
you use nested FOR loops and specify domains and key fields in each loop, for 
example, DATATRIEVE can use a key-based index only for evaluating the RSE 
in the last FOR loop. 

If all other conditions are equal, it is better to use a domain name than a collec- 
tion name in the last position of a key-based relational query. But there is one 
more factor to consider. Collections are efficient to use if you need to refer back to 
the same group of records in the same DATATRIEVE session. This is especially 
true if the collection is much smaller than the data file from which it is formed. 
In such a case, you may get better performance by forming and naming a collec- 
tion so that DATATRIEVE does not have to retrieve the same group of records 
over and over again. 

To summarize, you gain efficiency with a domain when you can use keyed 
access. You gain efficiency with a collection if you reduce the number of times 
DATATRIEVE must isolate the same small group of records from a large body 
of records. 

17.4.2.3 Ordering the Domains in Nested FOR Loops — If one FOR loop must pro- 
cess many more records than the others and all have the same key field, include 
the larger record stream in the last (inner) FOR loop. Similarly, if only one FOR 
loop can use keyed access, make sure that FOR loop is the last, or innermost, 
loop you specify. 

17.4.2.4 Restoring Indexed Files That Are Often Modified — If you add, erase, or 
change many records in an indexed file, that file can degrade DATATRIEVE per- 
formance. When you have erased many records from an indexed file, records in 
the file can occupy many noncontiguous areas of the disk. This slows down record 
access. When you add records to a file or change many values in key fields, the 
index for the file can be split over many noncontiguous areas of the disk. This 
also slows down record access. The more keys you define for each file, the more 
quickly DATATRIEVE response time degrades when you make many changes to 
the file. 

If you have a DATATRIEVE performance problem and you have made many 
modifications to your indexed file, restructuring your domain might improve 
DATATRIEVE response time. When you restructure a domain, you are recreat- 
ing the data file. When the new file is created, the records and index are stored as 
much as possible on contiguous areas of the disk. 
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Follow the same steps given in Chapter 15 for reorganizing a data file. In this 
case, however, specify the same organization for your new file rather than a dif- 
ferent one. If you have defined many different keys for your file, you might want 
to eliminate any keys that you seldom use in queries. If you define as keys only 
those fields that you often use in queries, modifying your file has less effect on 
DATATRIEVE response time. 

You can also restructure files and indexes using the RMS-11 utilities CONVERT 
and IFL. These utilities are explained in the RMS-11 manuals in your operating 
system documentation set. The D ATATRIE VE-1 1 utility program QCPRS, 
explained in Chapter 20 of this manual, can be used to restructure files and 
indexes. 

17.4.3 Avoiding Nested FOR Loops Followed by a Conditional 
Statement 

Try to avoid using nested FOR loops to control the execution of a conditional 
statement. The following example is extremely inefficient: 

DTR> FOR A IN 0WNERS(RET) 

C0N> FOR YACHTS(RET) 

C0N> IF TYPE = A . T Y PE(RET) 

C0N> THEN PRINT 50AT » A . NAME(RET) 

Wherever possible, include conditional tests as Boolean expressions within one 
of the RSEs. This effectively limits the number of records that DATATRIEVE 
has to process. The following example works much more efficiently than the pre- 
ceding one: 

DTR> FOR A IN OWNERS® 

C0N> FOR YACHTS WITH TYPE = A . T Y P E(RET) 
C0N> PRINT BOAT > A . N AME(RET) 
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Controlling Output 




When you invoke DATATRIEVE, several characteristics are set that control 
your display of input and output: 

o The number of columns in an output display (COLUMNS-PAGE) 

o The way DATATRIEVE responds to an ABORT statement ([NO] ABORT) 

• The presence or absence of Looking for... prompts ([NO] PROMPT) 

You can change these characteristics at any time during a DATATRIEVE ses- 
sion by using the forms of the SET command discussed in the following sections. 

1 8.1 Changing the Columns-Page Setting 

The default for the columns-page setting is 80 characters, the width of most 
video display screens. You can change this setting to fit your application and ter- 
minal characteristics. 

1 8.1 .1 Increasing the Columns-Page Setting 

You may want to increase the columns-page setting on your video diplay termi- 
nal or hardcopy terminal if you want to display detail lines more than 80 charac- 
ters long. If you have a VTlOO-family or VT200-family terminal and your 
command language is DCL, do the following: 

1. Use the DCL SET TERMINAL command to tell your system to increase the 
width of lines it can send you: 

$ SET TERMINAL/WIDTH= 132(ret) 
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Use the SET COLUMNS-PAGE command to increase the length of the line 
DATATRIEVE can display on your terminal. The maximum limit on the col- 
umns-page setting is 255. 

DTR> SET COLUMNS_PAGE = 132© 

Whatever the column setting on your terminal, you can continue a long input 
line by using a hyphen (-) continuation character at the end of the line. When 
you use a hyphen, DATATRIEVE does not check the syntax of your input until 
you press RETURN after a line that does not end in a hyphen. If the line you 
want to extend ends with a complete word, separate the hyphen from the word by 
entering a space. Otherwise, DATATRIEVE considers the characters at the 
beginning of the next line to be part of the same character string. 

1 8.1 .2 Decreasing the Columns-Page Setting 

To decrease the number of columns displayed, enter a SET COLUMNS-PAGE 
command: 

DTR> SET COLUMNS- PAGE = GO (ret) 
DTR> 

Decreasing the columns-page setting may cause problems when you display your 
output, however. If one of the elements in a print line is longer than the columns- 
page setting, DATATRIEVE displays an error message: 

DTR > SET COLUMNS_PAGE = 1 5® 
DTR > PRINT " 123a5G7890123456"(H) 
Print object too 1 a r 3 e for line width 

DTR > 

Notice that the columns-page setting does not affect the length of your input 
lines or the messages you receive from DATATRIEVE. 

Reducing the columns-page setting can also distort the display of a record as in 
the following example: 

DTR> READY YACHTS® 

DTR> PRINT FIRST 1 YACHTS® 

LENGTH 
OVER 

MANUFACTURER MODEL RIG ALL WEIGHT BEAM PRICE 

ALBERG 37 MK II KETCH 37 20,000 12 $3G»951 

DTR > SET COLUMNS-PAGE = 12® 
DTR> PRINT FIRST 1 YACHTS® 

(continued on next page) 
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MANUFACTURER 

ALBERG 
37 MK II 
KETCH 

37 

2 f 1 2 
$3B >951 

DTR> 

1 8.1 .3 Determining the Number of Columns You Need for a Print Line 

Several considerations determine the number of spaces, or columns, needed for 
each print object in the output line: 

• The actual length of the character string literal or numeric literal, or the 
length of the field or variable as specified by the record definition or the 
DECLARE command 

• The length of the field name, query name, query header, or longest segment of 
the query header 

• The length of the edit string 

The longest of these determines how many columns you need. 

To prevent crowding, DATATRIEVE also adds one space to the length of all fields 
except the last one on a line. To print a record from the YACHTS domain 
requires a minimum of 57 columns: 

• MANUFACTURER takes 13 columns; the query-header is 12 characters long. 

• MODEL takes 11 columns; the field is defined as 10 characters long: PIC 
X(10). 

• RIG takes 7 columns; the field is defined as 6 characters long: PIC X(6). 

• LENGTH_OVER_ALL takes 7 columns; the longest segment of the query 
header (LENGTH) is 6 characters long. 

• DISPLACEMENT takes 7 columns; both the query header (WEIGHT) and the 
edit string (ZZ,ZZ9) are 6 characters long. 

• BEAM takes 5 columns; the query header (BEAM) is 4 characters long. 

• PRICE takes 7 columns; the edit string ($$$,$$$) is 7 characters long, but no 
column is added because PRICE is the last field in the detail line. 
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If you set the columns to 56, the PRICE field no longer fits on one line. 
DATATRIEVE displays the price on the following line and omits the PRICE 
header: 

DTR> SET COLUMNS_PAGE = 5G© 
DTR> PRINT FIRST 1 YACHTS® 

LENGTH 
OUER 

MANUFACTURER MODEL RIG ALL WEIGHT BEAM 

ALBERG 37 MK II KETCH 37 20 ,000 12 

$3G ,951 

DTR > 



1 8.2 Using the SET ABORT Statement 

When DATATRIEVE executes an ABORT statement in a command file or proce- 
dure while SET NO ABORT is in effect, it affects only the compound statement 
containing the ABORT statement. If SET ABORT is in effect, DATATRIEVE 
terminates the remainder of the command file or procedure. The same rules 
apply if you enter CTRL/Z in response to a prompt. 

If DATATRIEVE encounters a syntax or logical error in a command file or proce- 
dure, it returns you to the DTR> prompt whether or not you have used SET 
ABORT. SET NO ABORT is the default setting when you invoke DATATRIEVE. 

See Chapters 9 and 10 for a discussion of using ABORT and NO ABORT in con- 
trolling procedures and command files. 

1 8.3 Using the SET PROMPT Statement 

When you invoke DATATRIEVE, SET PROMPT is in effect. If you press 
RETURN before finishing a command or statement, DATATRIEVE prompts you 
for the remaining required elements of that command or statement. 

The following sequence of commands and statements shows how DATATRIEVE 
responds when SET PROMPT is in effect. After the line of text indicates the next 
required element, DATATRIEVE displays the CON> (continuation) prompt. As 
long as the syntax of a command or statement is incomplete, DATATRIEVE uses 
CON> to tell you it is ready for further input. 



DTR> READY© 

[Looking for Dictionary Element] 
C0N> YACHTS© 
DTR> FIND© 

[Looking for "FIRST" > domain name* or collection name] 
C0N> FIRST© 

[Looking for a value expression] 
CDN> 1© 

[Looking for collection or domain name] 
CDN> YACHTS© 
CI Record found] 
DTR > 
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Notice that DATATRIE VE stops prompting as soon as you enter elements that 
comprise a syntactically complete command or statement. For example, READY 
YACHTS is complete, and DATATRIEVE does not prompt for any further ele- 
ment. Similarly, when you enter FIND FIRST 1 YACHTS, DATATRIEVE does 
not prompt you for a Boolean expression or a SORTED BY clause. 

When SET NO PROMPT is in effect, DATATRIEVE does not display the text 
about the next required element. It does, however, use the CON> prompt when 
the syntax is incomplete. The following example is identical to the previous one 
but has SET NO PROMPT in effect: 

DTR> SET NO PROMPT© 

DTR > F I ND(ret) 

CON> FIRST© 

C0N> 1 (RET) 

CON> YACHTS© 

CI Record found] 

DTR > 

Note that SET NO PROMPT does not suppress the messages DATATRIEVE dis- 
plays about the results of commands and statements. 



Controlling Output 18-5 



Controlling Access to Dictionary Objects 



To supplement your operating system protection, DATATRIEVE uses access con- 
trol lists (ACLs) to protect your data and dictionary definitions. An ACL, stored 
in the data dictionary, regulates user access to an object in the data dictionary. 

Every dictionary object (domain, record, procedure, and table) has an associated 
ACL. This chapter describes the contents of an ACL and the commands you use 
to maintain the ACL. It also shows a strategy to help ensure the integrity of your 
data. 

Carefully maintained ACLs can be effective against unauthorized browsing 
through files and accidental corruption of the dictionary or data. Use them to 
augment the overall security system for your installation. 

19.1 Contents of an Access Control List 

An ACL consists of one or more entries. Each entry contains the following 
information: 

• A sequence number 

• A lock type 

• A key 

• One or more access privileges 

Figure 19-1 shows a sample ACL containing three entries that illustrate the 
parts and options in an ACL. The table within Figure 19-1 identifies the parts of 
each entry. 
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DTR> SHOWP SAMPLE© 



1 fUIC t C254 ,203] » 

2 »PW # "SWORDFISH" t 

3 »UIC t I* »*] » "RE" 



RWEMC 

"RM" 



Sequence 
N u m be r 



LocK 



Key 



Privileges 



UIC 



[254 »Z03] 



RWEMC 



PW 



SWORDFISH 



RM 



3 



UIC 



[* »*] 



RE 



Figure 19-1 : Sample Access Control List 

19.1.1 Sequence Numbers 

Sequence numbers are sequential integers beginning with 1 that DATATRIEVE 
assigns to identify ACL entries. Use sequence numbers to identify entries you 
are adding to or deleting from the ACL. 

19.1.2 Lock Types 

Each entry in the ACL has a lock type that indicates whether you access the 
associated dictionary object by specifying a password or by using a UIC/PPN. 
There are two lock types: PW, for password, and UIC, for UIC/PPN. (A UIC/PPN 
represents an operating system account number.) 

19.1.3 Keys 

DATATRIEVE uses keys to identify you when you request access to dictionary 
objects. When you attempt to access a dictionary object, you must provide the 
correct password for a PW lock or own the correct UIC/PPN for a UIC lock. 

19.1.3.1 Password Keys — If the lock type is PW, the key is a 1- to 10-character 
password. You can use any character from the ASCII character set except the 
dollar sign ($). Examples of legal passwords include: FISH-FRY, SWORDFISH, 
1234, and PASSWD-9. 

To execute a command or statement that requires access privileges protected by 
a password, you include the password directly in the command or statement. For 
example, the domain YACHTS might contain only one ACL entry: 

1 PW SWORDFISH RWEMC 

To delete the YACHTS domain definition from the dictionary, you can specify the 
password enclosed in parentheses in the DELETE command: 

DTR> DELETE YACHTS (SWORDFISH)!© 
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For security reasons, you can also suppress the display of the password on your 
terminal. To do this, type an asterisk enclosed in parentheses ((*)) instead of the 
password. DATATRIEVE then prompts for the password but does not display the 
password when you enter it: 

DTR> DELETE YACHTS ( * ) 5 (ret) 

Enter password for YACHTS: (H) 

This technique for specifying a password is especially useful if you have a 
hardcopy terminal. 

19.1.3.2 UIC Keys - If the lock type is UIC (for UIC/PPN), the key is an account 
number known to the operating system. Under RSTS/E systems, an account 
number is called a project-programmer number, or PPN. Under other operating 
systems, the account number is called the user identification code, or UIC. The 
UIC/PPN consists of a 3-digit octal group number followed by a 3-digit octal user 
number. The numbers are separated by a comma and enclosed in brackets, for 
example [253,201]. 

A UIC/PPN lock can include specific numbers, asterisks, or a combination of an 
asterisk and a number. Asterisks allow all users or only users in a specified 
group to access a dictionary object. The following are valid ACL lock entries: 

o [253,201], allowing only the user with the account number [253,201] to have 
access 

• [253,*], allowing any user with group number 253 to have access 

• [*,*], allowing any user to have access 

For the UIC lock type, you do not include a UIC or PPN in a command or state- 
ment. Rather, DATATRIEVE verifies that you have access by checking the 
UIC/PPN you used to log in. For example, if the ACL for the procedure BIG- 
YACHTS contains just the following entry, then you must log in under [253,201] 
in order to access the procedure: 

1 UIC [253,201] RWEMC 

If the ACL contains the following entry, you can access the procedure regardless 
of your UIC/PPN: 

1 UIC [*»*] RWEMC 

Because you cannot use a password when invoking a procedure, you may want to 
use the UIC/PPN lock type to protect procedures. 

Note 

On RSX and VAX-11 RSX systems, a UIC must be in the range of 
[0,0] to [377,377]. On RSTS systems, a UIC must be in the range of 
[0,0] to [256,256]. 
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19.1.4 Access Privileges 



An access privilege determines the access you have to the associated dictionary 
object. You designate an access privilege by a single letter, a string of letters, or a 
space. Table 19-1 contains a list of access privileges and their description. 



Table 1 9-1 : Access Privileges 



Access 
Privilege 


Description 


R 


READ. The user can SHOW or EXTRACT the associated dictionary object. For a 
domain, the user can ready the domain for READ access only. 


W 


WRITE. The user can ready the domain for READ, EXTEND, MODIFY, or 
WRITE access to retrieve, modify, store, or erase records. 


E 


EXTEND or EXECUTE. For a domain, the user can ready the domain for 
EXTEND access only to store records. For a procedure, the user can execute the 
procedure. For a table, the user can refer to the table (using VIA or IN clauses). 
The user must have E access to a record to ready the associated domain. 


M 


MODIFY. The user can ready the domain for READ or MODIFY access to read or 
change records in the domain but not to add or delete. 


C 


CONTROL. The user can issue the commands DEFINEP, DELETE, REDEFINE, 
DELETEP, EDIT, and SHOWP. 


Space(s) 


No access. The user cannot access the dictionary object. 



Each entry in an ACL can include from one to five access privileges or designate 
no access. A space indicates that no access is permitted to a user with the corre- 
sponding key. For example, the single letter R specifies that a user with the cor- 
responding key has read access only. The letters RW specify that the user has 
both read and write access. Full access, designated by RWEMC, allows a user 
complete access to the dictionary object. If you specify a space, the user has no 
access to the dictionary object. 

Each access privilege allows you to issue certain commands and statements. For 
example, with R privilege, you can issue an EXTRACT command or ready a 
domain for read access. If you ready a domain to READ, you can then use com- 
mands and statements that display and manipulate the domain database. With 
only R privilege, you cannot ready a domain to WRITE, MODIFY, or EXTEND. 
Therefore, you cannot add to, delete, or modify data. 

Table 19-2 contains a list of commands that you can issue if you are granted the 
corresponding access privilege. The table also shows the statements you can use 
after issuing the command. 
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Table 19-2: Commands/Statements by Privilege 



Priwilono 
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(continued on next page) 
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Table 19-2: Commands/Statements by Privilege (Cont.) 



Privilege 


Commands 


Query 


lUI UUITldlll 


Dorm ittori 
rcl llllllcU 


oiaiernenis rerriiiiieu 


n 








DELETE 






REDEFINE 






DELETEP 






EDIT 






SHOWP 





Note 

You must have E access to the associated record definition to ready 
a domain. 



The meaning of E privilege differs depending on the dictionary object to which 
an ACL corresponds. In an ACL for a domain, E means extend privilege; that is, 
the user can store records in a file or extend it. In an ACL for a table, procedure, 
or record definition, E means execute privilege. The user can use a table or proce- 
dure, or ready the domain associated with the record definition. 

Only users with C (control) access to a dictionary object can directly access its 
associated ACL or edit or delete the dictionary object. However, any user with a 
group (or project) code of 1 (that is, a UIC/PPN in the form [l,n]) is automatically 
granted C (control) access to all ACLs. 

19.2 Creating Access Control Lists 

When you define a dictionary object, DATATRIEVE automatically creates an 
ACL for that object. The ACL initially contains only one entry, a UIC/PPN that 
is granted full access privileges to the dictionary object. The specific UIC/PPN 
stored in the ACL is installation-dependent and is determined when the 
DATATRIEVE software is installed. The entry can be in one of the following 
formats: 

[m,n] 

Full access privileges are granted to any user with the same UIC/PPN as the 
creator of the dictionary definition. For example, if you log in under [253,201] 
and create a procedure definition, then an entry for [253,201] is stored in the 
access control list for the procedure. Only users with a UIC/PPN of [253,201] 
can access the procedure. 
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[m*] 

Full access privileges are granted to any user with the same group (or pro- 
ject) code (m) as the creator of the definition. For example, if you log in under 
[253,201] and create a procedure definition, then an entry for [253,*] is stored 
in the access control list for the procedure. Any user with a group (or project) 
code of 253 (such as [253,222]) also has full access privileges to the procedure. 

[*,*] 

All DATATRIEVE users, regardless of their UIC/PPN, are granted full 
access to the dictionary object. 

Regardless of the default UIC/PPN stored in the ACL, the creator of the defini- 
tion always has full access privileges (RWEMC) to the dictionary object at the 
time he or she creates the definition. 

If you have C access to a dictionary object, you can grant privileges to additional 
users or further restrict the use of the dictionary object by changing its ACL. The 
commands you use to change the table are summarized later in this chapter and 
described fully in Chapter 5 of the DATATRIEVE-1 1 Reference Manual. 



19.3 Processing Access Control Lists in DATATRIEVE 

DATATRIEVE checks the appropriate access control list to verify that you have 
access privilege whenever you use a table, invoke a procedure, or issue one of the 
following commands: 

• DEFINEP 

• DELETE 

• DELETEP 

• EDIT 

• EXTRACT 

• READY 

• REDEFINE 

• SHOW 

• SHOWP 



Controlling Access to Dictionary Objects 1 9-7 



To verify that you have the correct access privilege, DATATRIEVE searches the 
ACL, checking each entry until it finds a match between the ACL key and your 
UIC/PPN or between the password you supply and one in the ACL. 
DATATRIEVE searches the table in the following sequence: 

1. DATATRIEVE stores your UIC/PPN and determines if you are a privileged 
user. A privileged user is one with a group (or project) code of 1 (that is, a 
UIC/PPN in the form [l,n]). At a minimum, DATATRIEVE grants a privi- 
leged user C (control) access. It may grant additional privileges, depending 
on the results of the following steps. 

2. DATATRIEVE checks the first entry in the access control list. 

If the lock type is PW, DATATRIEVE checks to see if you specified a pass- 
word in the command. If you did and the password matches the entry's key, 
DATATRIEVE stops searching the access control list and grants you the 
privilege or privileges listed in the entry. If the password does not match or 
you did not specify a password, DATATRIEVE performs the next step. 

If the lock type is UIC, DATATRIEVE checks to see if your UIC/PPN 
matches the key. If it does, DATATRIEVE stops searching the list and grants 
you the privileges listed in the entry. If the UICs do not match, 
DATATRIEVE performs the next step. 

3. DATATRIEVE checks the next entry in the list, following the same proce- 
dure as in the previous step. 

When there are no more entries, DATATRIEVE denies access to the diction- 
ary object and rejects your command or statement. 

The following examples show how DATATRIEVE handles some user requests. 
The examples use the following ACL for the domain YACHTS: 

DTR> SHONP YACHTS(ret) 



A user with UIC/PPN [253,201] enters a SHOW command to look at the defini- 
tion of the YACHTS domain. DATATRIEVE checks the user's UIC/PPN and 
finds it as the first entry. Because no access privilege is granted, access to the 
domain is denied to the user. 

DTR> SHON YACHTS 

Access denied to dictionary resource "YACHTS" 
DTR> 

A user with UIC/PPN [214,217] readies YACHTS for write access. The first 
match in the ACL (at entry 2) grants the user write (and control) privilege. The 
READY command executes: 

DTR> READY YACHTS WRITER 
DTR> 



1 »UIC » C253 fZOl ] t 

2 »UIC » C214 »Z17] t 
3,PUt "FISH-FRY"* 
a »UIC , [*.*]» " R " 



CW 
M" 
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A user with UIC/PPN [253,201] tries to ready YACHTS for modify access by 
including a password in the READY command. Because the entry in the ACL 
that contains the password FISH-FRY appears after the entry denying all privi- 
leges to the user, modify access to YACHTS is denied: 

DTR> READY YACHTS MODIFY (FISH-FRY)® 

Access denied to dictionary resource "YACHTS" 

DTR > 

A user with UIC/PPN [234,231] issues the same command as in the previous 
example. Because the user does not have the UIC/PPN that is denied all access 
and has included the correct password key for modify access, the READY com- 
mand executes: 

DTR > READY YACHTS MODIFY (FISH-FRY)© 
DTR> 

1 9.4 Maintaining an Access Control List 

To maintain an ACL that implements your security strategy, you must have C 
(control) access to the dictionary object associated with the ACL. Control access 
allows you to display an ACL and add or delete ACL entries. 

1 9.4.1 Guidelines for Ordering Entries 

When you add entries to an ACL, the order of entries in the ACL controls the 
access to the dictionary object. Place the most restrictive entries first in an ACL 
and the least restrictive entries last. The most restrictive entries completely 
deny access to a specific UIC/PPN, while the least restrictive entries allow access 
by any UIC/PPN. 

The following rules apply when adding entries to the ACL: 

• Place entries that deny all privileges first. Use a lock type UIC (instead of PW) 
for these entries. 

• Place restrictive entries that limit access to a specific UIC/PPN next. 

• Place the less restrictive entries (such as those requiring a password) next. 

• If access is allowed for any UIC/PPN (that is, if the key is [*,*]), place its entry 
last in the list. 
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19.4.2 Assigning Privileges 



If you know which commands or statements you want to permit a user to issue, 
use Table 19-3 to find the privileges you must assign to that user. 



Table 19-3: Privilege Requirements by Command/Statement 



Command/Statement 


Privilege Required 


DEFINEP 


C privilege for the dictionary object 


DELETE 


C privilege for the dictionary object 


UtiLtiLhitr 


C privilege for the dictionary object 


EDIT 


C privilege for the procedure or table 


EDIT ADVANCED 


C privilege for the domain or record 


ERASE 


W privilege for the domain and E privilege for the associated 
record 


EXTRACT 


R privilege for the dictionary object 


READY ...READ 


R, W, or M privilege for the domain and E privilege for the associ- 
ated record 


...WRITE 


W privilege for the domain and E privilege for the associated 
record 


...MODIFY 


M or W privilege for the domain and E privilege for the associated 
record 


...EXTEND 


E, W, or M privilege for the domain and E privilege for the associ- 
ated record 


SHOW domain-name 
record-name 
proc-name 
table-name 


R privilege for the dictionary object 


SHOWP 


C privilege for the dictionary object associated with the ACL 



Use care when assigning the W privilege, particularly if a more restrictive privi- 
lege (such as R or M) would suffice. The W privilege allows the user to perform 
the same functions as the R, M, and E privileges but also allows the user to issue 
the ERASE command to delete records. 

19.4.3 Displaying an Access Control List 

Use the SHOWP command to display an ACL: 



SHOWP object-name 
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1 9.4.4 Adding Entries to an Access Control List 

Use the DEFINEP command to add an entry to an ACL: 

^rr-^r-r, u- * [~ (passwd) 1 f PW, new-passwd 1 

DEFINEP object-name I VK ^ ' J sequence-no, | y|Q [ m n j \ . P nv 

Before adding any entry to an ACL, display the ACL using SHOWP. The follow- 
ing example illustrates adding one entry to an ACL: 

DTR> SHOWP YACHTS (FISH-FRY)® 

1 >PW i "FISH -FRY" * " RWEMC " 

DTR> DEFINEP YACHTS (FISH-FRY) 2, UIC» [201,213], R(ret) 
DTR> SHOWP YACHTS ( F I S H - F R Y ) (ret) 

1 »PN » "FISH-FRY" » "RWEMC " 

2 »UIC f [201 f 213] t "R" 

DTR> 

When you add an entry to an ACL, DATATRIEVE renumbers the entries that 
follow it so that their numbers occur in proper sequence. 

1 9.4.5 Deleting Entries from an Access Control List 

The DELETEP command deletes one entry from an ACL: 
DELETEP object-name ^ (P a sswd) J sequence-number 

Use the SHOWP command before deleting an entry to verify that you are delet- 
ing the correct entry. For example: 

DTR> SHOWP YACHTS ( F I SH - FR Y ) (ret) 

1 »PW t "FISH-FRY" , "RWEMC" 

2 »UIC » [201 1 213] » "R" 

DTR> DELETEP YACHTS (FISH-FRY) 2(retj 
D T R > SHOWP YACHTS ( F I SH - FR Y ) (ret) 

1 »PW , "FISH-FRY" , "RWEMC " 

D T R > 

After you delete an entry, DATATRIEVE renumbers the entries so that they are 
sequential, beginning with 1. 

An ACL must have at least one entry. DATATRIEVE does not allow you to 
delete an entry when that entry is the only one in the ACL. 

If you delete all entries that have C (control) privilege, there is only one way to 
change the ACL. Log in using a privileged UIC/PPN, invoke DATATRIEVE, and 
use the DEFINEP command to create an entry that gives one or more users the 
C privilege. 
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Maintaining Data Dictionaries 




A data dictionary holds domain, record, procedure, and table definitions. The 
items that you define in a data dictionary are called dictionary objects. 
DATATRIEVE supplies you with a default dictionary called QUERY. DIC. When 
you invoke DATATRIEVE, your current dictionary is QUERY.DIC. You can keep 
all your data definitions in QUERY.DIC, but it is orderly and efficient to store 
related definitions in separate dictionaries. You can create other data dictiona- 
ries with the CREATE DICTIONARY command. 

You can change from one dictionary to another, and you can display general and 
specific information about your current dictionary. You can also display informa- 
tion about readied domains, established collections, tables currently in memory, 
and selected records. 

You can transfer definitions stored in one dictionary to another dictionary by 
copying the definitions you want to a command file. You then set the destination 
dictionary as the current dictionary and execute the command file to store the 
definitions. 

You can also edit dictionary definitions. If you need to make only a few changes 
to an existing procedure or table, use the DATATRIEVE Editor, as described in 
Chapter 16. If you need to make extensive modifications to a procedure or table 
or want to edit a domain or record definition, you can copy the definition to a 
command file, exit from DATATRIEVE, edit the command file with the editor of 
your choice, and return to DATATRIEVE to execute the command file and store 
the new definition. 

The following sections discuss dictionary maintenance in detail. 
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You can list the names of all domains, records, procedures, and tables denned in 
the current data dictionary with the SHOW ALL command. SHOW ALL also 
lists the names of any established collections and readied domains: 

DTR> SHDH ALL© 
Domains: 

COMPANIES DDMF_TEST FAMILIES FODYAC 

□ LD_F AM I L I ES OWNERS PROJECTS YACHTS 

YACHTS_SEQUENTIAL 

Records: 

COMPANIES_REC FAMILY _REC OWNER.RECORD PROJECTS_REC 

Procedures : 

L0A_REP0RT PR I CE_PER_POUND TMP VERIFY 

Tables: 

The current dictionary is SY : C 2 * 1 ] QUERY . D I C 
No established collections 
No ready d o m a i n s 

You can print the definition of any dictionary object to which you have read 
access: 

DTR> SHOW FAMILIES© 
DOMAIN FAMILIES 

USING FAMILY _REC ON FAMILY.DAT 5 
DTR> 

The kind of access you have to a dictionary object depends on the access control 
list (ACL) associated with that object. The ACL specifies whether you have R 
(read), W (write), M (modify), E (execute), C (control) or no privilege for a diction- 
ary object. You can only display the ACL for a dictionary object if you have C 
(control) privileges. The following example prints the ACL for the domains 
FAMILIES and PROJECTS: 

DTR > SHOWP FAMILIES© 

1 ,UIC * [* ,*] t " RWMEC " 
DTR > SHOWP PROJECTS© 

1 »UIC > 123 >45] t "RWMEC " 

2 »PW * "SESAME" > "RE" 

DTR > 

See Chapter 19 for further information on controlling access to dictionary 
objects. 

20.2 Modifying Dictionary Objects 

To modify the definition of a dictionary object, you must have M (modify) access 
to the dictionary object. You can modify dictionary objects in the following ways: 

• You can use the DATATRIEVE Editor to modify definitions of procedures and 
tables. You cannot modify domains or records with the DATATRIEVE Editor, 
however. 
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• You can use the REDEFINE command to create a new definition. 
DATATRIEVE deletes the previous version of the object and allows you to 
define it a different way. The domain FAMILIES, for example, can be redefined 
as follows: 

DTR > SHOW FAMILIES® 
DOMAIN FAMILIES 

USING FAMILY _REC ON FAMILY.DAT j 
DTR > REDEFINE FAMILIES USING® 
DFN > NEW_FAMILY_REC ON NEW-FAMILY .DAT idD 
DTR > SHOW FAMILIES® 
DOMAIN FAMILIES 

USING NEW_FAMILY_REC ON NEW-FAMILY .DAT! 
DTR > 

Note 

The previous definition of an element will be permanently lost 
after a REDEFINE command is entered. If you make a mistake 
while entering the definition, you must enter it again from the 
beginning. 



• The easiest way to modify a dictionary element is probably to copy the defini- 
tion to a command file using the EXTRACT command: 

DTR > EXTRACT ON TEMP . CMD PERSON_REC® 
DTR > 

Exit DATATRIEVE and edit the command file using the text editor of your 
choice. After making the needed changes, return to DATATRIEVE and exe- 
cute the command file. 

The EXTRACT command adds both a DELETE command and a DEFINE 
command to the beginning of the indirect command file. When you execute the 
command file, the DELETE command removes the old definition of the diction- 
ary object from the current data dictionary, and the DEFINE command stores' 
the new definition in that dictionary. 

Note 

Use extreme caution when changing record definitions. If you 
change the record definition so that the record it describes no 
longer matches the record stored in your file, you can no longer 
access your data. Chapter 15 explains the relationship between 
your record definition and data access. 



The REDEFINE and EXTRACT commands do not copy the ACL associated with 
your record definition. When you redefine your record with the command file, 
DATATRIEVE also defines a new ACL for the record. This new ACL specifies the 
default privileges that have been set up for your system. 
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The QXTR utility, discussed later in this chapter, enables you to copy the ACL 
associated with your record to a command file. 



20.3 Deleting Dictionary Objects 

To remove the definition of a dictionary object from the current data dictionary, 
you must have C (control) access to the dictionary object. To remove a dictionary 
definition, use the DELETE command: 



DTR> SHOW DOMAINS® 
Domains: 

DDMF-TEST FAMILIES F00YAC OLD-FAMILIES 

OWNERS PROJECTS YACHTS YACHTS-SEQUENTIAL 

DTR > DELETE F00YAC 5 (ret) 

DTR > SHOW DOMAINS® 

Domains: 

DDMF-TEST FAMILIES OLD-FAMILIES OWNERS 

PROJECTS YACHTS YACHTS-SEQUENTIAL 

DTR > 



Remember to terminate the DELETE command with a semicolon. 

DELETE removes from the dictionary both the definition of the dictionary object 
and its associated ACL. This command does not delete the data file associated 
with a domain. The data file still resides in the directory where it was stored. 
Therefore, you can delete a domain definition and redefine it to access the same 
data file. 



20.4 Optimizing Disk Storage of Data Dictionaries with QCPRS 

The data dictionary is an indexed file stored on a disk. When you add and delete 
definitions from a dictionary, that file accumulates unused areas of disk space. To 
reclaim this wasted disk space, run the utility program QCPRS. QCPRS com- 
presses the contents of the dictionary, eliminating unused disk space. Com- 
pressing your dictionary can also improve DATATRIEVE performance. 

To compress a data dictionary, you should first determine how many blocks of 
storage your dictionary occupies. The following example determines the size of 
the dictionary KELLER.DIC that resides in directory [100,120] on the system 
disk. The example uses the DCL DIRECTORY command: 



$ DIRECTORY/FULL SY : CI 00 ♦ 1 20 ] KELLER 4 D I C(ret) 



The resulting display tells you the size (in blocks) of the dictionary. Later on, 
QCPRS prompts you for the number of blocks it should allocate for the com- 
pressed file. The number you supply should equal or exceed the number of blocks 
the dictionary currently uses. 

On a RSTS/E system, you should rename the dictionary before invoking the 
QCPRS utility. The easiest way to do this is to change the file extension: 



$ RENAME KELLER « D I C KELLER ♦ BAKlRET) 
$ 
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Then you invoke QCPRS in response to the operating system prompt. The follow- 
ing example assumes that you are using DCL to invoke QCPRS, which prints an 
identification message and requests a command with the following prompt: 



$ RUN $OCPRS 

QUERY FILE COPY-COMPRESS UTILITY 



CPR> 



Use the following format to compress the dictionary: 
new-file = old-file 

New-file is the file specification for the compressed copy of the dictionary. 
Old-file is the file specification of the dictionary to be compressed. If you omit a 
field in either file specification, QCPRS uses the following defaults: 



UIC/PPN Your default UIC/PPN 
file name QUERY 
extension DIC 

Under all operating systems but RSTS/E, the file specifications for new-file and 
old-file can be the same. QCPRS merely creates a new copy of the file using the 
next higher version number. 

Under RSTS/E, the file specifications for new-file and old-file must be different. 
Use the renamed dictionary from a previous example: 

QCP> KELLER. DIC = KELLER ♦ BAK(ret) 

After you have entered the file specifications, QCPRS asks you to specify a num- 
ber of disk blocks as an allocation for the new version of the dictionary: 

ENTER ALLOCATION FOR AREA 0: 

Enter the number of disk blocks you want to allocate for the compressed diction- 
ary. If the number is too low, QCPRS automatically extends the file to hold the 
contents of the original file. If the number is too high, the extra blocks remain in 
the file and give room for contiguous expansion of the dictionary. A number that 
is higher than what the file currently needs can help maintain DATATRIEVE 
performance for a longer period of time; however, the higher number wastes disk 
space over the short run. 

QCPRS then prompts again with CPR>, and you can compress another diction- 
ary file or terminate QCPRS with CTRL/Z. 



Field 



Default 



dev: 



SY: (the system device) 
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Because QCPRS does not alter the contents of the original file, you can save the 
file as a backup, or you can delete it. 

You can use QCPRS to compress an indexed data file associated with a 
DATATRIEVE domain as well as to compress a dictionary. If you have added 
many records to the indexed data file since the time you created it, compressing 
the file can help reduce DATATRIEVE response time to queries that access the 
file. Simply follow the steps you use to compress a dictionary, but specify the 
name and extension of the indexed file. 

20.5 Extracting Dictionary Content with the QXTR Utility 

You might want to transfer dictionary objects from one data dictionary to 
another or transport your dictionary objects to VAX DATATRIEVE. You can use 
the QXTR utility to create a command file containing all the definitions 
extracted from a D ATATRIE VE-1 1 data dictionary. Like QCPRS, QXTR is a dic- 
tionary maintenance program supplied with the D ATATRIE VE-1 1 installation 
kit. 

Running the QXTR program is equivalent to specifying all the objects in your 
dictionary in an EXTRACT command. However, the QXTR program also allows 
you to preserve the access control lists (ACLs) associated with each dictionary 
object. 

You must invoke QXTR from the system command level. The following example 
uses the DCL RUN command: 

$ RUN $0XTR@ 

Extract Utility for DTR Dictionaries U02.00 

QXTR then prompts you for the following information: 

• The file specification of the dictionary to be processed. 

• Whether you want to extract the access control list for each dictionary object. 

• If you respond with Y to the question on access control lists, whether you want 
those lists to use VAX DATATRIEVE syntax. 

• The name of the output command file to contain the extracted definitions. (The 
default is QXTR.CMD in your default directory.) 

When QXTR finishes processing your dictionary, it returns you to system com- 
mand level. The file QXTR creates an RMS sequential file you can invoke as an 
indirect command file for DATATRIEVE. 
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The following example processes the dictionary KELLER.DIC and copies the dic- 
tionary object definitions to LESLIE.CMD. The ACLs are extracted along with 
the objects. The ACLs remain in D ATATRIE VE-1 1 syntax: 

Dictionary Filespec to Extract from? KELLER . D I C(ret) 
Should Protection Tables be Extracted (Y or N ) ? Y(ret) 
Extract in VAX- 11 DATATRIEVE Syntax? N(ret) 
Filespec to Extract elements to? LESL I E . CMD(ret) 
$ 

Like the EXTRACT command in D ATATRIE VE, the QXTR utility precedes each 
dictionary object definition with a DELETE command. It also adds an 
ALLOCATION LEFT_RIGHT clause if no ALLOCATION clause is specified for 
record definitions. 

QXTR checks that you have R (read) privilege for the objects in the dictionary 
before extracting them. If you do not, it prints a message that the objects were 
not extracted, and the program continues. If you are logged in under a privileged 
account (with a UIC/PPN [l,x]), you can extract everything regardless of the 
access control list. If the access control list allows only password access and not 
UIC/PPN access, you must run QXTR from a privileged account to extract the 
element. The program checks your current UIC against the access control list. 

QXTR aborts if it encounters a corrupt dictionary object. In this case, the com- 
mand file contains definitions extracted before QXTR encountered the corrupt 
object. It does not contain the definition of the corrupt object or the definitions 
that would follow. DATATRIEVE extracts definitions in the following order: 
domains, procedures, records, and tables. Definitions of specific objects within 
these four types are extracted in alphabetical order according to the name of the 
object. Examine the incomplete command file to determine which dictionary 
object is corrupt. You must delete the corrupt object from the dictionary before 
running QXTR again. 
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When you use a field name as a value expression and when you display, modify, 
or erase one or more records, DATATRIEVE determines exactly which record or 
records are the targets of the action you propose. 

For each of these actions, DATATRIEVE must first determine the context within 
which the action occurs. The context is the set of conditions that govern the way 
DATATRIEVE recognizes field names and determines which records are the 
targets of DATATRIEVE statements. Understanding the way DATATRIEVE 
manages context is especially important when you begin nesting DATATRIEVE 
statements. 

Establishing the Context for Name Recognition 

DATATRIEVE does not require that every field name be unique. You can use the 
same name in several record definitions. You can even use the same name sev- 
eral times in the same record definition, as long as the fields with the identical 
name do not have the same level number in one group field. 

Both the YACHTS and OWNERS domains, for example, have group fields named 
TYPE, and both group fields contain elementary fields you can refer to with the 
names BUILDER and MODEL. (In YACHTS, DATATRIEVE recognizes the 
query name BUILDER as equivalent to MANUFACTURER. Other query names 
for YACHTS are SPECS, LOA, and DISP.) Figure A-1 shows the fields in both 
record definitions and points out the duplicate names. 

When you work with several record streams from the same domain, the field 
names in all record streams are identical. Whether you form collections or record 
streams of records from the YACHTS domain, DATATRIEVE has a mechanism 
for identifying which record to act on when you want to retrieve or change data 
from only one field of one record. 
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+ + 

! YACHTS ! 
+ + 

BOAT 

> TYPE 

> MANUFACTURER (BUILDER) 
MODEL 

SPECIFICATIONS (SPECS) 
RIG 

LENGTH_0'r'ER_ALL (LOA) 
DISPLACEMENT (DISP) 
BEAM 
PRICE 

Figure A-1 : Duplicate Field Names in YACHTS and OWNERS 

When you understand the way DATATRIEVE establishes the context for recog- 
nizing names, you can use the names of domains, fields, collections, and vari- 
ables to form both simple and complex relationships among fields. One of the 
keys to mastering the use of context is understanding the two DATATRIEVE 
context stacks. 

A.1 .1 The Right Context Stack 

When you issue a statement, DATATRIEVE builds a context stack, a linked 
list that controls the DATATRIEVE search for names to match the ones you use 
in statements. The context stack consists of context blocks, or lists of names. 
These context blocks are linked together by pointers that control the sequence of 
search by DATATRIEVE for values to associate with the names you use in 
statements. 

DATATRIEVE searches the right context stack for values to associate with 
names you use in print lists, Boolean expressions, and the right side of assign- 
ment statements such as x = y. The left context stack is discussed later in this 
appendix. 

A.1 .1 .1 The Content of a Context Block — When you use a record selection expres- 
sion, DATATRIEVE creates a context block to establish a context for name rec- 
ognition. That context block contains, among other things, a list of names. 

At the top of the list is a slot for the name of a context variable (see the section on 
context variables later in this appendix). Next is the name of the domain 
referred to in the record selection expression. The rest of the list contains the 
names of fields in the record associated with that domain. Those field names are 
arranged according to the field tree associated with the source. 

The field tree contains the names of all the group fields, elementary fields, 
COMPUTED BY fields, REDEFINES fields, and lists in the record and preserves 
the hierarchical relationships among them. 



+ + 

! OWNERS ! 

+ + 

OWNER 
NAME 

BOAT_NAME 

TYPE 

BUILDER 
MODEL 
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When DATATRIEVE searches for a name in the context stack, it is looking for a 
value to associate with that name. The search ends, and DATATRIEVE takes 
the associated value when it finds the first name that matches the one in your 
statement. 

A DATATRIEVE name can consist of several names joined together. They resem- 
ble dictionary path names in form and function. To be recognized, these com- 
pound or qualified names must represent a valid path through the hierarchy of a 
context block and the field tree it contains. 

When DATATRIEVE encounters a name, it begins its search in the context block 
on top of the stack. DATATRIEVE first looks at the slot in the context block 
reserved for the name of a context variable. For unnamed CURRENT collections, 
this slot contains the name CURRENT. For named CURRENT collections, the 
name CURRENT and the collection name are equivalent. Named collections 
that are not the CURRENT collection have the collection name in this slot. 

If the top block on the context stack refers to a record stream, this slot is empty 
unless you use a context variable in the RSE that forms the record stream. The 
context variable gives a record stream a temporary name; this name fills the first 
slot in the context block for these "named" record streams. 

If DATATRIEVE finds that the first segment of a qualified name matches the 
name in the collection name/context variable slot, it continues its search in that 
block for a match for the rest of the name. If the name in your statement does not 
match the name in the collection name/context variable slot, or if that slot is 
empty, DATATRIEVE continues to look through the first context block to find a 
match. 

Next in the context block is the name of the source of the records referred to by 
that block. For collections and record streams, that source can be the name of a 
domain, collection, or list for hierarchical records. The source can also be the 
name of a collection if you use the collection as the basis for a record stream in a 
FOR statement and you use a context variable. 

If the source name does not match the name in your statement, DATATRIEVE 
next looks for the name in the slot reserved for names. 

Next DATATRIEVE looks at the name of the top-level (the 01 level) field name. 
If no match occurs, DATATRIEVE looks at each succeeding field name in the 
order they are displayed when you enter a SHOW FIELDS command. That order 
can take you through the entire hierarchy of the field tree, traversing first the 
left branch then the right, wherever there is a branching point in the hierarchy. 

If DATATRIEVE finds no match in the first block on the context stack, it goes to 
the next context block on the stack and begins its search there. 

DATATRIEVE stops its search as soon as it finds an exact match for the name in 
your statement. Then it associates the value assigned to the name on the context 
stack with the name of the field in your statement. 
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If DATATRIEVE finds no match for the name in any of the context blocks, it dis- 
plays a message on your terminal that the field name is either undefined or used 
out of context. The only remedies are to change the context so that the name in 
your statement resolves properly or to remove any ambiguity by qualifying the 
name further with group field names or context variables. 

For the sake of clarity, the following description of the various types of context 
blocks starts with the bottom of the context stack, that is, with the context block 
that DATATRIEVE checks last. 

A.1 .1 .2 Global Variables — The bottom context block contains the names of any 
global variables you have established and have not released. This block is differ- 
ent from the others on the stack because its content is not determined by a record 
selection expression. Nevertheless, DATATRIEVE treats the name of a global 
variable as though it were the name of a field in a simple record. Just as 
DATATRIEVE associates the value of a field with the field name, DATATRIEVE 
associates the value of a global variable with its name. 

DATATRIEVE looks at the global variables last when trying to find a name to 
match one in your statement. No two global variables can have the same name. 
When you issue a DECLARE statement at command level (indicated by the 
DTR> prompt), DATATRIEVE checks the names of the global variables you 
have declared. If it finds one with the same name, it releases the old variable and 
its value and replaces it with the new one. DATATRIEVE initializes the new 
variable with a default value, a zero, or a space depending on the clauses you 
include in the DECLARE statement. 

A.1 .1 .3 Collections — The next higher set of blocks in the context stack refers to 
existing collections. Each collection with a block on the context stack must have 
one record singled out as a selected record. Although a collection can have a 
number of records in it, only one of those records can be used in the search for the 
context of a name. DATATRIEVE can assign only one value to the name. Conse- 
quently, that one value can come from only one of the records in the collection. 

Remember, the reason for resolving the context of a name you use in a statement 
is to assign a value to the name that can be used in the statement. 

For an existing collection, you can designate one record at a time as the selected 
record for that collection. The SELECT statement lets you designate the selected 
record in a collection by relative reference (FIRST, NEXT, and LAST) or by abso- 
lute reference to the position number of the record in the collection. A collection 
has a block on the context stack only if it has a selected record. 

If you have more than one existing collection with a selected record, the block 
immediately above the one for global variables refers to a named collection with 
a selected record. That collection is the one you formed with a FIND statement 
before you formed any of the other collections that have selected records. 

The rest of the context blocks for the collections with selected records are ordered 
according to the sequence in which you formed them, not the order in which you 
entered the SELECT statement to establish the selected records. 
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If the CURRENT collection has a selected record, the context stack contains a 
block referring to the CURRENT collection. That block is above the blocks of all 
other collections. DATATRIEVE searches for names in the context block of the 
CURRENT collection before it searches the context block of any other collection. 

The key to understanding the way DATATRIEVE recognizes names is that 
except for the global variables, the context stack is ordered on a last-in, first-out 
basis. The most recently formed context block is the one DATATRIEVE searches 
first. 

You do not have to rely on your memory to recall the order in which you formed 
your existing collections. You need only issue a SHOW COLLECTIONS com- 
mand. DATATRIEVE displays the most recently formed collection (always the 
CURRENT collection, whether it has a name or not) at the top of the list and the 
"oldest" one at the bottom. 

The SHOW COLLECTIONS command, however, lists all the existing collections 
whether or not they contain selected records. Remember, only the collections 
with selected records are represented on the context stack. 

With the SHOW collection-name command, you can inspect each existing collec- 
tion to see how many records are in the collection, whether it has a selected 
record, and, if it does, what the position number of the selected record is in the 
collection. 

If DATATRIEVE searches the context stack and does not find a match for the 
name in your statement, it displays an error message that may seem puzzling 
unless you understand the way DATATRIEVE forms the context stack: 

Field "name" is undefined or used out of context 

You may know the name has been defined, and that it is the name of a field in a 
record associated with one or more existing collections. If, however, none of the 
collections containing that field has selected records, DATATRIEVE cannot tell 
if the field is defined or not. 

If a collection containing the named field has no selected record, that collection 
has no block on the context stack. Consequently, DATATRIEVE neither finds a 
match for the field name nor has a way of discovering from the search of the con- 
text stack if the field name is defined at all. 

The order of context blocks at the higher levels of the context stack depends on 
the order in which DATATRIEVE encounters the elements containing names 
associated with values. The order of the following sections does not imply any 
relative position on the stack. Only the order DATATRIEVE encounters those 
elements determines their order on the stack. 

A.1 .1 .4 Record Streams - Before DATATRIEVE looks at the context block of 
the most recently formed collection with a selected record, it first looks at the 
context blocks created explicitly in the statement. One type of context block cre- 
ated by a statement refers to the field names of a record stream formed by a 
statement. 
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Context blocks of record streams act differently from those of collections. The 
context block for a collection stays on the stack as long as the collection has a 
selected record. The context block of a collection is removed from the stack only if 
you release the collection or remove its selected record with a DROP statement. 

The context block for a record stream, however, stays on the stack only as long as 
the statement containing it is being executed. When DATATRIE VE finishes 
processing the statement, the block is removed from the context stack and is not 
available when DATATRIE VE rebuilds the stack after it encounters the next 
statement. 

Only three statements and one command make lasting changes to the context 
stack: 

• FIND 

The FIND statement can remove the CURRENT collection from the context 
stack by forming a new CURRENT collection. The new CURRENT collection 
releases the old collection but does not put a block on the context stack because 
a newly formed collection has no selected record. 

• SELECT 

The SELECT statement puts a collection on the context stack by establishing 
a selected record. SELECT cannot change the relative order of collections on 
the stack. That order is determined by the relative order in which you formed 
the collections with the FIND statement. 

• DROP 

The DROP statement removes a collection from the context stack by dropping 
the selected record from the collection. The SHOW collection-name command 
still notes the position number of the previously selected record, but the record 
has been removed from the collection and you cannot retrieve it unless you 
form a new collection that contains it. 

• RELEASE 

The RELEASE command also removes a collection from the context stack. The 
released collection no longer exists, thus freeing the space it occupied. Records 
and domains associated with a collection named in the RELEASE command 
are not affected. 

These three statements, however, share a restriction that separates them from 
all other statements: you cannot use FIND, SELECT, or DROP statements in 
compound statements. They must be entered at command level by themselves. 
Furthermore, these statements do not form temporary record streams; they 
affect only collections. 
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You can, however, have several context blocks for record streams on the context 
stack at one time. The block for a record stream stays on the context stack until 
DATATRIEVE finishes the statement. Because you can nest statements in FOR 
loops, BEGIN-END blocks, IF-THEN-ELSE statements, THEN, and WHILE 
statements, the inner statements can form record streams before DATATRIEVE 
finishes the outermost statement. 

DATATRIEVE has to keep the context of outer statements separate from that of 
inner ones. It keeps them separate by putting a block on the context stack when 
it encounters an element that requires one. DATATRIEVE begins processing 
compound statements with the outermost statement and works progressively 
toward the innermost one. The context blocks it forms for elements in the inner- 
most statement are at the top of the stack when the innermost statement is 
being processed. 

When DATATRIEVE finishes processing the innermost statement, it removes 
the blocks created by that statement. DATATRIEVE works its way back out 
toward the outermost statement, removing blocks created by statements as soon 
as it finishes processing the statement. For example, in the case of nested FOR 
loops, the context block for the innermost FOR loop is higher in the stack than 
the blocks for the outer loops. 

When DATATRIEVE completes the execution of the innermost loop, it removes 
the context block of that FOR statement, leaving the blocks of the outer FOR 
statement on the stack. As DATATRIEVE completes each loop, the context block 
for that loop is removed from the stack. This same pattern applies to statements 
in BEGIN-END blocks. 

When a statement that forms a record stream is followed by a second statement 
that is not contained in the first, DATATRIEVE removes the context block cre- 
ated for the first statement from the stack and puts a context block for the second 
statement in its place. For example, in a BEGIN-END block, one PRINT state- 
ment containing an OF rse clause follows another. The context block of the first 
statement is in effect only during the execution of that first statement. That 
block is replaced by the one for the second PRINT statement when 
DATATRIEVE begins processing the second statement. 

DATATRIEVE handles the context block of a FOR loop the same as it handles 
statements containing an OF rse clause. 

DATATRIEVE creates four other types of context blocks that affect the order of 
the context stack: those for local variables, VERIFY clauses, VALID IF clauses, 
and context variables. 

A.1 .1 .5 Local Variables — Local variables are variables defined in compound 
statements. A local variable and its effect on the context stack last only from the 
DECLARE statement that defines it until DATATRIEVE completes the execu- 
tion of the statement containing the DECLARE statement. 
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A.1 .1 .6 VERIFY Clause in the STORE Statement — Like the context for local vari- 
ables, the context for resolving field names in a VERIFY clause of the STORE 
statement is short-lived. The STORE statement does not access or change any 
existing record. Consequently, for each STORE statement, DATATRIEVE cre- 
ates a context block to associate the field names with the values in the new 
record. DATATRIEVE executes the VERIFY clause after you have assigned val- 
ues to all the fields prescribed by the syntax of the statement but before 
DATATRIEVE stores the record in the data file. 

A.1 .1 .7 VALID IF Clause in a Record Definition — When you assign a value to a 
field name in either a STORE or MODIFY statement, DATATRIEVE looks in 
the appropriate record definition for a VALID IF clause. If the value is unaccept- 
able according to the conditions specified in the VALID IF clause, DATATRIEVE 
displays a message on your terminal and reprompts you for an acceptable value. 
It uses the same context to associate the field name with your response to the 
reprompt. 

The context for resolving field names in the VALID IF clause is established by 
the context block set up for either: 

• The STORE statement 

• The MODIFY statement 

In either case, the value associated with the field name is the one just assigned to 
it by your response to a prompt or by an assignment statement in the USING 
clause of the STORE or MODIFY statement. 

DATATRIEVE executes the VERIFY clause only after the values you assign 
meet the conditions of VALID IF clauses in the record definition. As a result, 
there can be no conflict between the context established for these two clauses. 
The context for the VALID IF clause no longer exists when DATATRIEVE exe- 
cutes the VERIFY clause. 

A.1 .2 Using Context Variables and Qualified Field Names 

The ways of establishing context discussed to this point deal with resolving the 
connections between names and values by finding the first instance of a valid 
field name or variable name. When several context blocks on the stack contain 
fields with the same names, you need a way to skip over some instances of the 
name to get to the field that contains the value you want to retrieve. 

DATATRIEVE gives you two methods of forcing name recognition: context vari- 
ables and qualified field names. Although they require different actions from 
you, these two methods have an underlying similarity. 

A.1 .2.1 Context Variables as Field Name Qualifiers — A context variable is a 

dummy variable specified in a record selection expression for the purpose of 
name recognition. When DATATRIEVE encounters a context variable, it puts a 
new block on the context stack. That new block connects the name of the context 
variable with the field names and values of the records identified by the record 
selection expression. 
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The context established by the context variable lasts until DATATRIEVE com- 
pletes the execution of the statement containing the record selection expression 
in which the context variable occurs. However, that context does not affect any 
outer loops or nesting statements that contain the statement in which you use 
the context variable. 

A context variable, however, does affect all inner statements nested in the state- 
ment that contains the record selection expression in which the context variable 
occurs. 

You can use the context variable as a prefix for each field name of the records 
identified by the record selection expression. Citing a field name with a context 
variable prefix can make a field name unique, even when the domains and field 
trees of a record in a record stream are identical. 

Putting a prefix on a field name produces a qualified field name. The context 
variable must be the first prefix added to a field name. 

A.1 .2.2 Other Field Name Qualifiers — Using other qualifiers as prefixes to field 
names is the second method of overriding the DATATRIEVE default mechanism 
of name recognition. 

Each fully qualified field name must be unique. The fully qualified field name 
consists of the record name, the top-level group field name, the names of any 
group field to which the elementary field belongs, and the elementary field 
name. You must separate each element of the fully qualified name from the next 
with a period. For example, in the domain YACHTS, the fully qualified field 
name of MODEL is: 

YACHT . BOAT ♦ TYPE ♦ MODEL 

You can use these elements in any combination that preserves their hierarchical 
order to distinguish the MODEL field in YACHTS from the MODEL field in 
another domain such as OWNERS. 

When DATATRIEVE encounters a qualified field name, it searches the context 
stack for the first match of the name you specify. For example, if you use 
BOAT.MODEL in a record selection expression, DATATRIEVE searches the con- 
text stack for the first valid occurrence of the name BOAT and searches the 
branches of the hierarchy under BOAT for the first valid occurrence of the name 
MODEL. 

The success of the search is not jeopardized because you omit the group field 
name TYPE from the qualified name MODEL. DATATRIEVE searches the 
entire hierarchy under BOAT until it finds the first valid occurrence of TYPE. 
When an intermediary group field name is omitted, DATATRIEVE searches the 
hierarchy according to the order in which the fields of the record were defined. 

Fully qualified field names are adequate when working with two or more 
domains that share elementary or group field names, or both. However, when 
you are working with two record streams from the same domain, you must fur- 
ther qualify the field name with a context variable. This extra qualification is 
especially necessary when dealing with lists in hierarchical records. 
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Suppose you want to display information about all builders who build boats with 
more than one type of rig. YACHT is the given name of the record associated 
with the domain YACHTS. The field tree of YACHT has the structure: 

YACHTS 

01 BOAT 
03 TYPE 

OB MANUFACTURER 
OB MODEL 
03 SPECIFICATIONS 
OB RIG 

OB LENGTH_OVER_ALL 
OB DISPLACEMENT 
OB BEAM 
OB PRICE 

You can print the desired information with nested FOR loops. For each boat from 
the outer FOR statement, you want DATATRIE VE to loop through all the boats 
and find all the ones with the same builder. For each one it finds, you want it to 
compare its rig with the rig of the boat from the outer loop. Then you want to 
separate out the ones for which the rigs are not the same. At first, you might be 
tempted to use the following statement to produce the desired list: 

DTR > SET NO PROMPT© 
DTR > FOR YACHTS© 

C0N> FOR YACHTS WITH BUILDER = BUILDER AND© 

C0N> RIG NE RIG© 

C0N> PRINT BUILDER* RIG, RIG© 

DTR > 

After a long search for records, DATATRIEVE displays no records. The problem 
is that the preceding syntax asks DATATRIEVE to look for a boat with a rig that 
is not equal to itself — an obvious contradiction. Both of the fields named RIG 
resolve to the record stream formed by the second FOR statement. The name 
BUILDER also resolves to the same record stream. 

When you enter this statement, DATATRIEVE takes the first record from 
YACHTS but does not look at any of the values in its fields. Then it looks at 
every record in YACHTS and discovers that for every one of them, the name of 
the builder equals itself, but that no rig is not equal to itself. Thus every record 
in YACHTS fails to meet the condition set by the statement. 

DATATRIEVE then takes the second record in YACHTS and once again goes 
through all the boats, finding that the two values are always equal to themselves 
and thus fail to meet the impossible demands of the statement. And so it goes for 
each record: two comparisons for 113 times 113 records, and no records meet the 
self-contradictory conditions. 
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The problem is how to get D ATATRIEVE to look at the builder and rig of the 
outer FOR statement when making the comparison. The context variable pro- 
vides one solution: 



DTR > FOR A IN YACHTS© 

CON> FOR YACHTS WITH BUILDER = A, BUILDER AND RIG NE A , R I G(ret) 
CON> PRINT BUILDER* A. RIG* RIG© 

MANUFACTURER RIG RIG 

AMERICAN SLOOP MS 
AMERICAN MS SLOOP 
CHALLENGER SLOOP KETCH 



PEARSON KETCH SLOOP 

PEARSON KETCH SLOOP 

DTR > 

In this case, the use of the context variable A forces D ATATRIEVE to look to the 
record stream formed by the outer FOR statement. At the same time, 
DATATRIEVE recognizes the unqualified names, RIG and BUILDER, in the 
context established by the most recent RSE: the one in the second FOR state- 
ment. The conditions in the second FOR statement are no longer impossible, and 
information from 62 records is displayed. 

The way DATATRIEVE treats the unqualified names in this example illustrates 
another rule for context resolution: the left-hand member of a Boolean expres- 
sion must resolve to the record selection expression of which it is a part. If you 
start the Boolean expression in the second FOR statement with A.BUILDER, 
DATATRIEVE tells you that A.BUILDER is undefined or used out of context. 

You can add a second context variable in the previous example to make sure the 
resolution of the names is explicitly stated: 

DTR > FOR A IN YACHTS© 

CON> FOR B IN YACHTS WITH B. BUILDER = A.BUILDER AND B ♦ R I G NE A . R I G(ret) 
C0N> PRINT B. BUILDER* A, RIG* B . R I G© 

You gain two advantages by specifying the second context variable: clarity of 
representation and certainty that DATATRIEVE will display an error message 
if you make a syntax error. Using the second context variable, however, does not 
allow you to violate the rule for resolving field names on the left side of Boolean 
expressions. 

A.1 .3 The Left Context Stack for Assignment Statements 

When you make assignment statements at DATATRIEVE command level or as 
part of STORE or MODIFY statements, DATATRIEVE must assign values to 
the field or variable you intend. It uses the left context stack to associate the val- 
ues you supply with the fields and variables you want the values assigned to. 
Blocks on the left context stack are for records and variables that you can 
update. 
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Whenever DATATRIE VE begins to process a statement, the left context stack 
contains the global variables you have declared and not released. Any local vari- 
ables you declare in compound statements are also on the left context stack. The 
local variables are removed when the statement in which you declared them 
ends. 

Local and global variables are on both stacks. Each type of variable has a value 
that can be assigned to a field or another variable; hence, they are on the right 
context stack. Both can be updated with new values you assign them; hence, 
they are on the left context stack. 

Context blocks for a record you want to modify is also on both context stacks. The 
record has a value you can use in Boolean expressions and assignment state- 
ments. You can update that value in a MODIFY statement. Because a field is on 
both stacks at the same time, you can use the old value of the field to calculate 
the new value. You can use the following form of assignment statement: 



DTR > MODIFY USING PRICE = PRICE * 1 ♦ 1(H) 
DTR > 



DATATRIEVE retrieves the old value of PRICE associated with the name on the 
right context stack and multiplies the old PRICE by a constant. It then associ- 
ates that value with the name PRICE on the left context stack and updates the 
value of the PRICE field. 

When you enter a STORE statement, the only context block for the new record is 
on the left context stack. No record exists yet, and, of course, no values are asso- 
ciated with fields of a record. The fields can only receive values. 

However, as soon as DATATRIEVE associates a value with a field, you can move 
that value to the right context stack and use it on the right side of assignment 
statements. You can make this shift before you finish assigning values to all the 
fields of the new record. In fact, you can use the values of new fields to calculate 
the values DATATRIEVE stores in other new fields in the same record. 

To shift newly stored values to the right context stack, include a context variable 
with the domain name when you enter the STORE statement: 

DTR > STORE A IN YACHTS USING , , , 

Then in the USING clause, you use the context variable to qualify the names of 
any field whose value you want to use on the right side of an assignment 
statement: 



DTR > STORE A IN 
CON> BEGIN© 
C0N> Fl = val 
C0N> F2 = ual 
CON> F3'= A ♦ F 
CON> END(RET) 
DTR > 



YACHTS US I NG(ret) 

ue-expressi on [ret] 
ue-expressi on [ret] 
1 + A « F2(RET) 
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The context variable allows you to associate a field name on the right context 
stack with its new value as soon as you assign the value to the field. You cannot, 
however, use a field name on the right side of an assignment statement until you 
have assigned a value to the field. 

A.1 .4 Examples of Context Variables in STORE and MODIFY 
Statements 

You can combine STORE and MODIFY statements to keep an audit trail of mod- 
ifications made to records in a domain and to change statistical records when you 
store new records. 

To form an audit trail you need a domain for the audit records. This domain can 
use the same record definition as the original domain, but it must have its own 
domain definition and its own data file. Here is a simple example: 



DTR > SHOW AUDIT - YACHT S®) 
DOMAIN AUDIT-YACHTS USING 

YACHT ON AUD-YACHT5 
DTR> FOR A IN YACHTS MODIFY USING® 
CON> BEG I N(ret) 

CON> BUILDER = * . BU I LDER® 

CON> MODEL = *, MODEL® 

CON> RIG = *.RIG® 

CON> LOA = * ♦ LO A®) 

CON> DISP = *♦ WEIGHT® 

CON> BEAM = *.BEAM® 

CON> PRICE = *. PRICE® 

CON> STORE B IN AUDIT-YACHTS USING® 

CON> B . BOAT = A. BOAT® 

C0N>END® 

Enter BUILDER: 



If you have a VERIFY USING clause in the MODIFY statement, put the STORE 
statement as the last statement in the VERIFY clause. If you put the VERIFY 
clause after the STORE statement and the VERIFY clause aborts the change, 
you have a record of the change, but you have not changed the record. 

You can also embed a MODIFY statement in a STORE statement. In this exam- 
ple, the embedded MODIFY statement updates a record of the last date a new 
record was added to the data file and records the TYPE field of the record stored. 
The file LAST.DAT is a sequential file with one record in it. 



DTR > SHOW LAST-ENTRY® 

DOMAIN LAST-ENTRY USING LAST-REC ON LAST ♦ DAT 5 
DTR > SHOW LAST-REC® 
RECORD LAST_REC USING 
01 TOP. 

03 LAST-DATE USAGE DATE. 

03 TYPE PIC K(20) . 

5 

DTR> STORE YACHTS USING® 
C0N> BEGIN® 

C0N> BUILDER = *. BUILDER® 
C0N> MODEL = *. MODEL® 
C0N> RIG = *.RIG® 

(continued on next page) 
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CON> LDA = * ♦ LO A(ret) 

CON> DISP = *. WEIGHT© 

CON> BEAM = # ♦ BEAM(ret) 

CON> PRICE = *.PRICE(ret) 

CON> MODIFY LAST-ENTRY USING© 

CON> BEGIN 

CON> LAST_DATE = "TODAY "(ret) 

CON> B . TYPE = A ♦ TY PE(ret) 

CON> END 
CON >END(reT| 
Enter BUILDER : 

With the proper use of context variables, you can also store or change data in 
fields shared by two or more domains. 

A.2 Single Record Context 

The DATATRIEVE statements PRINT, MODIFY, and ERASE can act on one 
record at a time or on an entire record stream or collection. The records on which 
they act are called target records. You can identify target records for these 
statements in four ways: 

• A SELECT statement identifies one target record in a collection. 

• The keyword ALL in the statement without an OF rse clause makes all records 
in a collection the targets of the statement. 

• An OF rse clause in the statement forms a target record stream. 

• The RSE clause in a FOR statement forms a stream of target records for the 
statement contained in the FOR loop. 

A.2.1 The SELECT Statement and the Single Record Context 

Before discussing the SELECT statement and context, a short review of facts 
about collections is in order. 

DATATRIEVE keeps a list of the collections you form with the FIND statement. 
The most recent one formed is always at the top of the list and is called the 
CURRENT collection. The only other collections on the list are the ones to which 
you assigned a name when you formed them. The next collection you form then 
becomes the new CURRENT collection. DATATRIEVE discards the old 
CURRENT collection unless you give it a name when you form it. 

With the RELEASE command, you can remove a collection from that list. If you 
release the CURRENT collection, the next one on the list becomes the 
CURRENT collection. 

No collection on this list, however, is represented by a block on the context stack 
unless you use the SELECT statement to single out one record in the collection. 
When you select a record in a collection, DATATRIEVE puts a block for that col- 
lection on the context stack. If every existing collection has a selected record, 
then DATATRIEVE keeps a block on the context stack for each of those 
collections. 
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The relative ages of the collections with selected records determine the order of 
context blocks for collections. The "oldest" collection with a selected record is 
nearest the bottom of the context stack. Because the CURRENT collection is 
always the "youngest," its context block, if it has one, is nearest the top. 

This order of context blocks for collections establishes the order DATATRIEVE 
uses not only for recognizing field names as described previously, but also for 
identifying single target records. When you enter the most abbreviated forms of 
the PRINT, MODIFY, and ERASE statements, DATATRIEVE looks on the con- 
text stack for the first valid single record context to carry out the specified action. 
It looks for the youngest collection with a selected record and either prints the 
record, erases it, or changes it. 

The following sequence of examples illustrates the effect of the SELECT and 
DROP statements on single record context and the subsequent actions of the 
PRINT, MODIFY, and ERASE statements. 

Form a collection of records from the YACHTS domain, call it BIGGIES, select 
the third record as the target record, and display it: 

DTR > READY YACHTS WRITE© 

DTR > FIND BIGGIES IN YACHTS WITH LOA > 40© 
C8 records found] 
DTR > SELECT 3© 
DTR > PRINT© 

LENGTH 
OUER 

MANUFACTURER MODEL RIG ALL WEIGHT BEAM PRICE 

GULFSTAR 41 KETCH 41 22*000 12 $41*350 

DTR > 

Store a new record in the YACHTS domain and form a collection that consists of 
that one record. Later you can modify and erase this record: 



DTR > STORE YACHTS© 

Enter MANUFACTURER: HINKLEY© 

Enter MODEL: BERMUDA 40© 

Enter RIG: YAWL© 

Enter LENGTH_OVER_ALL : 40© 

Enter DISPLACEMENT: 20000© 

Enter BEAM: 12© 

Enter PRICE: 82 1 000© 

DTR > FIND YACHTS WITH BUILDER = "HINKLEY"© 
CI record found] 
DTR > 
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You now have two collections, CURRENT (the younger) and BIGGIES (the 
older): 



DTR > SHOW COLLECT I ONS© 
Collections: 

CURRENT 

BIGGIES 

DTR > SHOW CURRENT® 
Collection CURRENT 

Domain: YACHTS 

Number of Records: 1 

NoSelecte d Record 
DTR > SHOW BIGGIES© 
Collection BIGGIES 

Domain: YACHTS 

Number of Records: 8 

Selected Record: 3 

DTR > 

The CURRENT collection has no selected record, but BIGGIES still does. 
Consequently, when you type PRINT and press the RETURN key again, 
DATATRIEVE prints the record in the first valid single record context, that is, 
the selected record in BIGGIES: 



DTR > PRINT© 

MANUFACTURER MODEL 

GULFSTAR 41 
DTR > 



LENGTH 
OVER 

RIG ALL WEIGHT BEAM PRICE 



KETCH 



41 



22 ,000 12 $41 ,350 



When you type SELECT and press the RETURN key, DATATRIEVE selects the 
first and only record in the CURRENT collection. Now when you type PRINT 
and press the RETURN key, the single record context has changed. Now the 
selected record in the CURRENT collection is the target record of the PRINT 
statement: 

DTR > SELECT(ret) 
DTR > PRINT© 



MANUFACTURER MODEL RIG 
HINKLEY BERMUDA 40 YAWL 

DTR > SHOW CURRENT® 

Collection CURRENT 

Domain: YACHTS 
Number of Records: 1 
Selected Record: 1 

DTR > 



LENGTH 
OVER 

ALL WEIGHT BEAM PRICE 



40 



2 » 00 12 $82, 
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Now modify the PRICE of the target record and display the result. The MODIFY 
and PRINT statements both act on the record in the first valid single record con- 
text, that is, the selected record in the CURRENT collection: 

DTR> MODIFY PRICE© 
Enter PRICE: 75*000© 
DTR > PRINTED 

LENGTH 
OVER 

MANUFACTURER MODEL RIG ALL WEIGHT BEAM PRICE 

HINKLEY BERMUDA 40 YAWL 40 20*000 12. $75 ,000 

DTR > 

Now type ERASE and press the RETURN key. The ERASE statement also acts 
on the record in the first valid single record context, and the record for the 
HINKLEY boat is removed from the data file YACHT.DAT Even though you 
erase the only record in the collection, DATATRIE VE does not discard the collec- 
tion. It takes note that you have erased the selected record and removes the con- 
text block for the CURRENT collection from the context stack. You can verify 
the change in single record context by typing PRINT and pressing RETURN. 
The selected record from BIGGIES is again in the first valid single record 
context: 

DTR > ERASE® 

DTR > SHOW CURRENT© 

Collection CURRENT 

Domain: YACHTS 

Number of Records: 1 

Selected Record: 1 
DTR > PRINT© 

LENGTH 
OYER 

MANUFACTURER MODEL RIG ALL WEIGHT BEAM PRICE 

GULFSTAR 41 KETCH 41 22*000 12 $41*350 

DTR > 

If you type MODIFY or ERASE and press the RETURN key, and no existing col- 
lection has a selected record, DATATRIEVE displays a message that there is no 
target record for the action you propose: 

DTR> ERASE© 

No target record for ERASE* 
DTR > MODIFY© 

No selected record for modify 
DTR > 
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However, if you type PRINT and press the RETURN key, and no existing collec- 
tion has a selected record, DATATRIEVE displays a message that there is no 
selected record and then prints out the whole collection: 

DTR > FIND YACHTS WITH BUILDER = "ALBIWdTj 
[ 3 records found] 
DTR > PRINT© 



No record selected* 


printing 


whole collection 








LENGTH 










OVER 






MANUFACTURER MODEL 


RIG 


ALL 


WEIGHT BEAM 


PRICE 


ALB I N 79 


SLOOP 


2G 


4 »200 10 


$17 ,900 


ALBIN BALLAD 


SLOOP 


30 


7>27B 10 


$27 t500 


ALBIN VEGA 


SLOOP 


27 


5 »070 08 


$18 »B00 



DTR > 



You can change the single record context with the DROP statement. The DROP 
statement removes the selected record from a collection but does not erase the 
record from the data file. When you type DROP and press the RETURN key, and 
the CURRENT collection has no selected record, DATATRIEVE displays a mes- 
sage on your terminal: 

DTR > FIND BIGGIES IN YACHTS WITH LOA > 40 (ret) 
C8 records found] 
DTR > DROP© 

No collection with selected record for DROP* 
DTR > 

If the CURRENT collection has a selected record, the DROP statement removes 
that record from the collection when you type DROP and press the RETURN key. 
If other collections have selected records, you must specify the collection name in 
the DROP statement. 

The CURRENT collection is BIGGIES. Select and display the first record in 
BIGGIES and form a new CURRENT collection of boats built by Albin: 

DTR > select; print© 

LENGTH 
OVER 

MANUFACTURER MODEL RIG ALL WEIGHT BEAM PRICE 

CHALLENGER 41 KETCH '41 26 »700 13 $51*228 

DTR> FIND YACHTS WITH BUILDER = "ALBIN "(ret) 
C3 records found] 
DTR > 
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Now select, display, and drop the first record of the CURRENT collection. Then 
enter a SHOW CURRENT command to see how DATATRIE VE records the 
results of your actions. The SELECT statement creates a single record context 
for the current collection, thus the target record of the PRINT statement is the 
selected record in the CURRENT collection, not in BIGGIES: 

DTR > SELECT© 
DTR > PRINT© 

LENGTH 
□ UER 

MANUFACTURER MODEL RIG ALL WEIGHT BEAM PRICE 

ALB I N 79 SLOOP 2G .4*200 10 $17*900 

DTR > DROP© 

DTR > SHOW CURRENT© 

Collection CURRENT 

Domain: YACHTS 

Number of Records: 3 

Selected Record: 1 

DTR > 

When you drop a selected record from a collection, you change the single record 
context. The context block for that collection is removed from the context stack. 

Consequently, when you type PRINT and press the RETURN key again, 
DATATRIE VE displays the selected record in BIGGIES, the record in the first 
valid single record context: 

DTR > PRINT© 

LENGTH 
OVER 

MANUFACTURER MODEL RIG ALL WEIGHT BEAM PRICE 

CHALLENGER 41 KETCH 41 2G *700 13 $51*228 

DTR > 

Like PRINT, MODIFY, and ERASE, the DROP statement acts on the record in 
the first valid single record context. 

If you type PRINT and press RETURN when you have no valid single record con- 
text, DATATRIE VE displays the whole CURRENT collection because there is no 
selected record in either of the two existing collections. Because you dropped one 
record from the CURRENT collection, it contains only two records now: 

DTR > PRINT© 

No record selected* printing whole collection 

LENGTH 
OVER 

MANUFACTURER MODEL RIG ALL WEIGHT BEAM PRICE 

ALBIN BALLAD SLOOP 30 7 »27G 10 $27*500 

ALBIN VEGA SLOOP 27 5*070 08 $18 #600 

DTR > 
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To show that you have not erased the record dropped from the CURRENT collec- 
tion, form and display a new CURRENT collection of boats by Albin: 



DTR > FIND YACHTS WITH BUILDER = "ALBIN "(ret) 
[3 records found] 
DTR > PRINT ALL© 



MANUFACTURER 



MODEL 



RIG 



LENGTH 
OVER 
ALL 



WEIGHT 



BEAM 



PRICE 



ALBIN 
ALBIN 
ALBIN 



73 

BALLAD 
MEGA 



SLODP 
SLODP 
SLDDP 



2(3 
30 
27 



a >200 
7 >27G 
5 .070 



10 
10 
08 



$17 ,300 
$27 ,500 
$18 *E00 



DTR > 



A.2.2 The CURRENT Collection as Target Record Stream 

The preceding example shows the effect of the keyword ALL on a PRINT state- 
ment that does not contain an OF rse clause. 

Although DATATRIEVE acts on only one record at a time, you can identify more 
than one record for a single DATATRIEVE statement to act on. With the 
keyword ALL, you can make every record in the CURRENT collection the target 
of a single PRINT, MODIFY, or ERASE statement. Such a statement, however, 
cannot also contain an OF rse clause. 

If you have a CURRENT collection and type PRINT ALL and press the 
RETURN key, DATATRIEVE displays the whole CURRENT collection. If you 
have no CURRENT collection, DATATRIEVE displays a message on your termi- 
nal. To illustrate this effect, release all collections and enter the statement 
PRINT ALL: 

DTR > SHOW COLLECT I 0NS(RETJ 
Collections: 

CURRENT 

BIGGIES 

DTR > RELEASE CURRENT* BIGGIES® 
DTR > SHOW COLLECTIONS© 
No established collections. 
DTR > PRINT ALL© 

A current collection has not been established* 

DTR > 

DATATRIEVE displays the same message on your terminal when you have no 
CURRENT collection and you enter an ERASE ALL or MODIFY ALL 
statement. 

When you have a CURRENT collection and enter an ERASE ALL statement, 
DATATRIEVE removes every record in the CURRENT collection from the data 
file. Although frequently useful, this operation can jeopardize valuable data if 
you use it carelessly. 
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Note that if your collection contains many records and you mistakenly enter an 
ERASE ALL or MODIFY ALL statement, you can enter CTRL/C to prevent all 
the records in the CURRENT collection from being erased or changed. How 
many records get erased or changed under such circumstances depends on the 
speed with which you enter CTRL/C, the processing load on your system, and the 
priority of your process. 

The various forms of the MODIFY ALL statement change the data in each 
record of the CURRENT collection (see the DATATRIEVE-1 1 Reference 
Manual). Make a collection of the first three yachts with no listed price. Display 
the CURRENT collection, modify the PRICE to $30,000, display the results of 
the change, and change the price back to zero using a different form of the 
MODIFY ALL statement: 



DTR > FIND FIRST 3 YACHTS 
C3 records found] 
DTR > PRINT ALLlRET) 


! WITH 


PRICE = 


0(REJJ 






MANUFACTURER MODEL 


RIG 


LENGTH 
OVER 
ALL 


WEIGHT 


BEAM 


PRICE 


block i, ao 

BUCCANEER 270 
BUCCANEER 320 


SLOOP 
SLOOP 
SLOOP 


39 
27 
32 


18 »500 
5 fOOO 
12 .500 


12 
08 
10 




DTR > MODIFY ALL PRICE© 
Enter PRICE: 30 00 (ret) 
DTR > PRINT ALLdT) 












MANUFACTURER MODEL 


RIG 


LENGTH 
OVER 
ALL 


WEIGHT 


BEAM 


PRICE 


block I. ao 

BUCCANEER 270 
BUCCANEER 320 


SLOOP 
SLOOP 
SLOOP 


39 
27 
32 


18 ,500 
5 »000 
12 .500 


12 
08 
10 


$30 »000 
$30 »000 
$30 »000 


DTR > MODIFY ALL USING PRICE = 


5 PRINT 


ALL(RET) 






MANUFACTURER MODEL 


RIG 


LENGTH 
OVER 
ALL 


WEIGHT 


BEAM 


PRICE 


block i . ao 

BUCCANEER 270 
BUCCANEER 320 


SLOOP 
SLOOP 
SLOOP 


39 
27 
32 


18 »500 
5 > 
12 »500 


12 
08 
10 





DTR > 



A. 2.3 The OF rse Clause and Target Record Streams 

The OF rse clause in a PRINT, ERASE, or MODIFY statement lets you create a 
new context for that statement. The OF rse clause specifies a target record 
stream that overrides any context established for your existing collections. For 
each such clause, DATATRIEVE puts a new block on the context stack. When 
DATATRIEVE completes execution of the statement, it removes that block from 
the context stack. 
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The following example contrasts the effect of PRINT, PRINT ALL, and PRINT 
OF rse. (When the PRINT statement does not include a list of fields, you can 
omit the OF from the statement.) The record selection expression here is FIRST 
3 YACHTS WITH PRICE = 0. This RSE identifies a new target record stream 
for the PRINT statement that overrides the CURRENT collection as a target 
record stream. It also overrides the single record context of the selected record in 
the CURRENT collection: 

DTR > FIND FIRST 3 YACHTS© 
C3 records found] 
DTR > SELECT! PR I NT(ret) 

LENGTH 
DYER 



MANUFACTURER MODEL 


RIG 


am 

H l_ l_ 


li r t r u t 


RET AM 


ppTrc 
r ix l l> c. 


ALBERG 37 MK II 


KETCH 


37 


20 1 


12 


$3B »951 


DTR > PRINT ALL(ret) 












MANUFACTURER MODEL 


RIG 


LENGTH 
OVER 
ALL 


WEIGHT 


BEAM 


PRICE 


ALBERG 37 MK II 
ALBIN 79 
ALBIN BALLAD 


KETCH 
SLOOP 
SLOOP 


37 
2G 
30 


2 1 

a >200 

7 ,278 


12 
10 
10 


$38 »351 
$17 ,900 
$27 »500 


DTR > PRINT FIRST 3 YACHTS WITH 


PRICE = 


0(RETj 






MANUFACTURER MODEL 


RIG 


LENGTH 
OYER 
ALL 


WEIGHT 


BEAM 


PRICE 


BLOCK I ♦ 40 
BUCCANEER 270 
BUCCANEER 320 


SLOOP 
SLOOP 
SLOOP 


33 
27 
32 


18 »500 
5 fOOO 
12 »500 


12 
08 
10 





DTR > 



To reduce the risk to your data, DATATRIEVE forces you to include both 
keywords ALL and OF when using the OF rse clause in MODIFY and ERASE 
statements. Although the results are not shown here, you must type MODIFY 
and ERASE statements to resemble the following examples. The record selection 
expression used in these statements is PHONES WITH DEPT = "32T": 

DTR > MODIFY ALL OF PHONES WITH DEPT = "32T" 

DTR > MODIFY ALL DEPT OF PHONES WITH DEPT = "32T" 

DTR > MODIFY ALL USING DEPT = _*."NEW DEPT" OF PHONES WITH DEPT = "32T 
DTR > ERASE ALL OF PHONES WITH DEPT = "32T" 
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Unless you include an assignment statement in the USING clause of a MODIFY 
statement, DATATRIEVE prompts you once to supply a value for each elemen- 
tary field specified or implied in the statement. After you respond to the last of 
the prompts, DATATRIEVE begins to change each of the records in the 
CURRENT collection to correspond to the values you supplied to the prompts. 
You can prevent any changes from taking effect by entering CTRL/Z when 
responding to any of the prompts. 

A.2.4 FOR Statements and Target Record Streams 

You can use FOR statements to create target record streams for the 
DATATRIEVE statements that use single record context. Using FOR loops has 
an advantage over using target record streams formed by the OF rse clause and 
the target record stream formed of the CURRENT collection by the keyword 
ALL. The FOR statement lets you work with each record individually; you do not 
have to perform the same operation on all target records. By putting STORE and 
MODIFY statements and prompting value expressions in a FOR loop, you can 
act on each member of a record stream or collection one at a time. 

When you put a MODIFY statement in a FOR statement, DATATRIEVE 
prompts you once for each field in the record if you do not specify a field list or a 
USING clause in the MODIFY statement. 

This FOR statement creates a record stream of boats that have no price listed. 
The MODIFY statement prompts you to supply a price for each record in the 
record stream. You can put a unique value in the PRICE field for each boat: 

DTR >RE ADY YACHTS MODIFY© 

DTR >F0R YACHTS WITH PRICE = MODIFY PRICE© 
Enter PRICE: 12900© 
Enter PRICE: 15600© 
Enter PRICE: 



DTR > 

Another valuable feature of FOR loops is the complex relationships you create 
between record streams when you include one FOR loop inside another. Each 
FOR statement puts a block on the context stack. As a result, you can use the 
context mechanism to transfer values between records. 

By putting a MODIFY statement inside two FOR statements, you can automati- 
cally update master records with the data from periodic transaction records: 

DTR > FOR A IN DAILY - TRANSACTION S© 



C0N> FOR B IN MASTER-DATA WITH B . ACCOUNT = A.ACCOUNT© 

C0N> MODIFY USING© 

C0N> BEGIN© 

C0N> MASTER-BAL = MASTER-BAL - WITHDRAW + DEPOSIT© 

C0N> TOT_WITHDRAW = T0T_W I THDRAW + WITHDRAW© 

C0N> T0T_DEP0SIT = T0T_DEP0SIT + DEPOSIT© 

C0N> END© 
DTR > 
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The Boolean expression in this example limits the record stream for the inner 
FOR statement to one record. 

You can also create nested FOR statements in which DATATRIE VE executes a 
series of statements at each level of nesting. For each owner record in the next 
example, DATATRIE VE asks you if you want to modify the SPECS of every boat 
in the YACHTS inventory built by the manufacturer of the the owner's boat. The 
third time through the outer loop, DATATRIEVE again begins the cycle of 
prompting for the boats by Albin because the third person in the OWNERS 
domain also owns a boat by Albin. Notice that the record changed during the 
second loop appears during the third: 

DTR >SET NO PROM PT (ret) 
DTR >F0R OWNERS© 
CON >BEG I N©) 



CON> PRINT SKIP* BUILDER* SKIP© 

CON> FOR YACHTS WITH BOAT, BUILDER = OWNER ♦ BU I LDER© 

C0N> BEGIN© 

CON> PRINT SPECS© 

C0N> IF *."D0 YOU WANT TO CHANGE THIS" CONT " Y " © 

CON> THEN MODIFY SPECS© 

C0N> END© 



C N > E N D 
BUILDER 



ALBERG 





LENGTH 










OUER 








RIG 


ALL 


WEIGHT 


BEAM PRICE 




KETCH 


37 


20 >000 


12 $36,000 




Enter 


DO YOU 


WANT TO 


CHANGE THIS: 


N© 


ALBIN 










SLOOP 


2B 


4 ,200 


10 $17,800 




Enter 


DO YOU 


WANT TO 


CHANGE THIS: 


N© 


SLOOP 


30 


7 ,276 


10 $27*500 




Enter 


DO YOU 


WANT TO 


CHANGE THIS: 


N© 


SLOOP 


27 


5 ,070 


08 $18*600 




Enter 


DO YOU 


WANT TO 


CHANGE THIS: 


Y© 


Enter 


RIG: KETCH© 






Enter 


LENGTH- 


OVER-ALL: 35© 




Enter 


DISPLACEMENT: 


17000© 




Enter 


BEAM: 1 


2© 






Enter 


PRICE: 


33000© 







(continued on next page) 
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ALB I N 



SLOOP 2G a»200 10 $17*900 

Enter DO YOU WANT TO CHANGE THIS: N(ret) 

SLOOP 30 7>27G 10 $27*500 

Enter DO YOU WANT TO CHANGE THIS: N(H) 

KETCH 35 17>000 12 $33*000 

Enter DO YOU WANT TO CHANGE THIS: N(ret) 



C&C 



SLOOP 31 8»G50 09 

Enter DO YOU WANT TO CHANGE THIS: 
Execution terminated by operator 
DTR > 
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Access control list 

adding entries to, 19-11 

contents, 19-1 to 19-6 

control (C) privilege, 20-2 

creating, 19-6 to 19-7 
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domains, 1-2, 4-1 to 4-3 

records, 5-1 to 5-18 
DELETE command, 1-3, 16-5 to 16-6 
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terminated by semicolon, 20-4 
DELETEP command, 1-3 
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Dictionary objects 
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function and use of, 1-5 to 1-7 
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restructuring, 15-1 to 15-9 
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sample, 2-2 

views, 13-1 to 13-9 
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DTR.TSK, 1-5 
DTR> prompt, 2-4 
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E 
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Editor, 16-1 to 16-14 
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DELETE command, 16-5 to 16-6 
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invoking, 16-1 to 16-2 
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modes, 16-2 
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Editor (cont.) 

REPLACE command, 16-9 to 16-10 

sample editing session, 16-13 to 16-14 

SUBSTITUTE command, 16-10 to 16-11 

TYPE command, 16-11 to 16-12 
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defined, 5-5 to 5-6 
EMPLOYEE_REC 

valid field names, 5-7F 
END_PROCEDURE clause, 9-2 
END_REPORT statement (Report Writer), 2-4 
END_TABLE clause, 12-3 
EQUAL relational operator, 7-4 
ERASE statement, 1-3 

restrictions, 6-2 
Error messages, 2-5 

incorrectly named fields, 5-6 

located by a procedure, 9-6 to 9-7 
EXIT command, 1-3, 2-6, 16-6 
Exiting DATATRIEVE, 2-6 
EXTRACT command, 1-3, 9-14, 20-3 

copying record definitions, 5-3 

F 

FAMILIES sample domain, 2-2 

using list field, 5-13 

using SHOWP, 20-2 
Field definitions, 5-3 to 5-12 

clauses, 5-10 to 5-12 

clauses in, 1-2 

EDIT_STRING clause, 5-4 

elementary fields, 5-5 to 5-6 

group fields, 5-5 to 5-6 

level numbers, 5-4 to 5-6 

naming fields, 5-6 

PICTURE clause, 5-4 

rules for writing, 5-3 to 5-12 

terminated by period (.), 5-4 

valid field names, 5-7F 
Field names 

duplicate, 5-7 to 5-8 

FILLER, 5-8 to 5-9 

restrictions, 5-6 to 5-7 

use of hyphens or underscores, 1-2 
Fields 

alphanumeric, 5-10 

Computed by, 5-11 

date, 5-11 

definition clauses, 5-10 to 5-12 

PICTURE, 5-10 

USAGE, 5-11 to 5-12 
elementary and group, 1-2 
list, 5-13 
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naming, 5-6 
numeric, 5-11 
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denning, 1-2, 6-1 to 6-8 
indexed, 6-1 to 6-8 
criteria for using, 6-2 
denning, 6-4 
sequential, 6-1 to 6-7 
criteria for using, 6-2 
defining, 6-3 to 6-4 
FILLER fields 

as group field name, 5-9 
FIND statement, 1-3 
FINISH command, 1-3 
FIRST n clause 

in RSE, 7-3 
Flat records, 5-14F 
FOR statement, 8-3 

creating target record streams, A-23 to A-25 
FROM clause, 13-2 

G 

Global variables, 11-4 

named in context block, A-4 
GREATER_EQUAL relational operator, 7-6 
GREATER_THAN relational operator, 7-6 
Group fields 

as primary key, 6-5 

defined, 5-5 to 5-6 

using FILLER field, 5-9 
Guide mode, 2-3, 2-8 

invoking, 2-8 

using a question mark (?), 2-8 

H 

HELP command, 1-3, 2-6 to 2-7 

ADVANCED HELP, 2-7 
Hierarchies, 14-1 to 14-12 
defining, 5-13 to 5-18 
eliminating empty print lines, 14-9 
retrieving values 
sublists, 14-11 to 14-12 
using ALL in nested print lists, 14-5 
using FIND and SELECT statements, 
14-3 

using nested RSEs, 14-9 
using OF rse clause, 14-5 
with nested FOR loops, 14-9 



Hierarchies (cont.) 

saving space, 5-13 

using, 5-14 to 5-18 
Hyphen (-) 

continuation character, 5-6 

conversion to underscore (_), 1-2, 4-1 

in record name, 5-3 

I 

IF-THEN-ELSE statement, 8-5 
IN relational operator, 12-5 
Indexed files, 6-1 to 6-8 

compared with sequential, 6-2T 

compressing, 20-6 

defining, 6-4 

multikey, 6-3 

optimizing storage, 20-6 
Input line prompt, 2-4 
INSERT command, 16-6 to 16-8 
Installation kit, 2-2 
Interactive DATATRIEVE, 1-5 
Invoking 

DATATRIEVE, 2-1 to 2-2 

K 

KEY clause, 6-4 
Keys 

accessing dictionary objects, 19-2 
defining alternate keys, 6-5 
defining key fields 
rules for, 6-6 

L 

LESSJEQUAL relational operator, 7-6 
LESS_THAN relational operator, 7-6 
Line pointer, 16-2 
Lists 

changing length of, 5-18 

defining fixed occurrences, 5-15 to 5-16 

defining variable occurrences, 5-16 to 5-17 

defining with OCCURS clause, 5-13 to 5-18 

nesting to form sublists, 5-17 
Lists, in records 

See Hierarchies 
Local variables, 11-4 to 11-5 

effect on context stack, A-7 
Lock types, 19-2 
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M 

MAX clause, 5-18, 6-7 
Memory, conserving 

See Optimizing workspace 
MODIFY statement, 1-3, 2-5 

changing fields, 6-2 

N 

NO CHANGE, 6-8 
NO DUP, 6-8 

NOT Boolean operator, 7-8 
NOT EQUAL relational operator, 7-4 
NOT IN relational operator, 12-5 
Numeric fields, 5-11 

o 

OCCURS clause, 5-13 to 5-18 

changing list length, 5-18 

defining hierarchical records, 5-14 

fixed number of occurrences, 5-15 to 5-16 

variable number of occurrences, 5-16 to 5-17 
OCCURS FOR clause, 13-2 
OF rse clause 

targeting record streams, A-21 to A-23 
Operating systems 

for DATATRIEVE, 1-1 
Optimizing 

response time, 17-6 to 17-9 

with keyed access, 17-6 to 17-9 

workspace, 17-5 
OR Boolean operator, 7-8 
Output 

controlling, 18-1 to 18-5 

default settings, 18-1 
OWNERS sample domain, 2-2 

P 

Passwords 

keys, 19-2 
Period 

in field definition, 5-4 
PERSONNEL sample domain, 2-2, 2-3 

record data items, 5-2F 
PERSONNEL_REC 

record level numbers, 5-4 

sample record definition, 5-2F 
PICTURE clause, 5-10 

in field definition, 5-4 
Pool space 

See Workspace 



PRINT statement, 1-3 
lists, 14-9 

retrieving data, 2-3 
Privileges 

assigning, 19-10 
Procedures, 1-4, 9-1 to 9-16 

aborting, 9-12 to 9-13 

comments in, 9-5 

compared with command files, 10-1 

contents, 3-1, 9-3 to 9-5 

defining, 9-1 to 9-2 

deleting, 9-15 to 9-16 

displaying, 9-14 

editing, 9-14 to 9-15 

in compound statements, 9-10 to 9-12 

invoking, 9-2 to 9-3 

locating errors, 9-5 to 9-7 

maintaining, 9-13 to 9-16 

nesting, 9-8 to 9-10 

samples, 9-7 to 9-8 

SET ABORT/SET NO ABORT, 9-12 to 9-13 
Prompting value expressions 

for storing and modifying values, 2-5 
Prompts 

CON>, 2-4 

DFN>, 2-4 

DTR>, 2-4 

RW>, 2-4 

syntax, 2-5 
Protecting dictionary tables, 12-9 

Q 

QCPRS utility 
conserving disk space, 20-4 to 20-6 
data dictionary compression, 20-4 
defaults, 20-5 

improving performance, 20-4 
invoked by Digital Command Language, 
20-5 

QED> prompt, 16-3 to 16-14 
Query names 

specifying, 5-12 
QUERY.DIC default dictionary, 20-1 
QUERY.INI file, 2-2 

sample, 2-3 

SET DICTIONARY in, 2-3 

SET GUIDE in, 2-3 
QUERY_HEADER clause, 5-10 
QUERY_NAME clause, 5-10 
Question mark (?) 

used in Guide mode, 2-8 
QUIT command, 16-8 
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QXTR utility, 20-6 to 20-7 
creating command files, 20-6 
transferring data dictionary objects, 20-6 

R 

READY command 

gaining access to domains, 1-3 

retrieving data, 2-3 
Record definition 

changing, 15-1 to 15-9 

contents, 3-1 

field definitions within, 5-3 to 5-12 
steps in writing, 5-1 to 5-18 
using OCCURS clause, 5-14 
VALID IF clause, A-8 
Record selection expression, 7-1 to 7-10 
accessing records, 7-2 
ALL clause, 7-2 
Boolean expressions, 7-4 to 7-6 
definition, 7-1 
FIRST n clause, 7-1 to 7-3 
limiting the number, 7-3 
retrieving field values, 5-8 
SORTED BY clause, 7-1, 7-9 to 7-10 
tables, 7-7 

WITH clause, 7-1, 7-4 to 7-9 
record selection expression 

tables, 12-5 
Record stream, 7-1 
sorting 
by field values, 7-9 to 7-10 
Record streams 

context block, A-5 to A-7 
Records 
comparing, 7-4 to 7-6 
defining, 1-2, 5-1 to 5-18 
field definitions within, 5-3 to 5-12 
field level numbers, 5-4 to 5-6 
specifying names, 5-2 to 5-3 
with variable length list, 5-16 to 5-17 
deleting, 6-2 

example data items, 5-2F 

flat, 5-14F 

grouping 
by table reference, 7-7 
in range of values, 7-6 to 7-7 

hierarchical, 5-14 to 5-18 

limiting access, 13-3 

limiting fields in a, 13-3 

modifying, 6-2 

rules for naming, 5-3 

sample definition, 5-2F 
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selecting 
conditional expressions, 7-4 
REDEFINE command 

changing domain definitions, 15-2 to 15-9 
REDEFINES clause, 5-10 
Relational operators, 7-4 to 7-8 

summary of, 7-7T 
RELEASE command, 1-3 
Remote Terminal Interface, 1-6 to 1-7 
REPEAT statement, 8-1 to 8-3 
REPLACE command, 16-9 to 16-10 
REPORT statement, 1-3 

retrieving data, 2-3 to 2-4 
Response time 

reducing with QCPRS utility, 20-4 
Restructuring domains 

examples, 15-1 to 15-9 
Retrieving data, 2-3 to 2-4 
RMS facility 

capabilities, 6-1 to 6-3 
RSE 

See Record selection expression 
RW> prompt, 2-4 

s 

Sample editing session, 16-13 to 16-14 
Security 

dictionary definitions, 19-1 to 19-11 
Semicolon 

with DEFINE DOMAIN command, 4-2 

with DELETE command, 20-4 
Sequence numbers, 19-2 
Sequential files, 6-1 to 6-7 

compared with indexed, 6-2T 

defining, 6-3 to 6-4 
SET ABORT command, 10-5, 18-4 

effect on ABORT statement, 18-4 
SET COLUMNS_PAGE command, 18-1 to 

18-4 
SET command 

terminal control, 1-3 
SET DICTIONARY command, 3-3 

in QUERY.INI file, 2-3 
SET GUIDE command, 2-8, 10-3 

in QUERY.INI file, 2-3 
SET NO ABORT command, 10-5 
SET PROMPT command, 18-4 to 18-5 
SET TERMINAL command, 18-1 
SHOW ALL command, 20-2 
SHOW command, 1-3, 2-2 

with domains, 4-3 
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SHOW DICTIONARY command, 3-2 to 3-3 

SHOW TABLES command, 12-7 

SHOWP command, 1-3 

SIGN clause, 5-10 

Single record context, A-14 

SORT statement, 1-3 

SORTED BY clause, 7-9 to 7-10 

Specifying domain names 

DEFINE DOMAIN command, 4-1 to 4-2 
Startup banner, 2-1 
Statements 

See Commands and statements 
STORE statement, 1-3, 2-5 
Sublists, 5-17 

retrieving values, 14-11 to 14-12 
SUBSTITUTE command, 16-10 to 16-11 
SUM statement, 1-3 
SUPERSEDE clause, 6-7 
System security 

using access control lists, 19-1 to 19-11 

T 

Tables, 12-1 to 12-9 
and workspace, 12-7 

code/translation strings, 1-4, 12-1 to 12-6 

creating, 12-3 to 12-4 

defining, 3-1 

defining and using, 12-4 

deleting, 12-9 

displaying, 12-7 

displaying contents, 12-7 to 12-8 

editing, 12-3 to 12-4, 12-8 

functions and uses of, 1-4 

IF-THEN-ELSE statement, 12-5 to 12-6 

in a record selection expression, 12-5 

maintaining, 12-9 

protecting, 12-9 

sample, 12-1 to 12-2 

using IN relational operator, 12-4 

VALID IF clause, 12-6 

validating data, 12-6 

VIA value expression, 12-6 to 12-7 

WITH in, 12-5 
Task size, reducing 

See Optimizing workspace 
TYPE command, 16-11 to 16-12 



u 

UIC 

See User identification code 
Underscore (_), 1-2, 4-1 

in record name, 5-3 
USAGE clause, 5-10, 5-11 to 5-12 
User identification code, 3-3 

keys, 19-2 to 19-3 

V 

VALID IF clause, 5-10 

in record definition, A-8 
Variables, 11-1 to 11-9 

as counters, 11-6 to 11-9 

declaring, 11-1 

global, 11-4 

local, 11-4 to 11-5 

storing values, 11-2 to 11-6 
VERIFY clause 

in STORE statement, A-8 
VIA value expression, 12-6 to 12-7 
View domains, 13-1 to 13-9 

combining data, 13-4 to 13-5 

containing a list, 13-7 to 13-9 

defining, 13-2 

limiting record access, 13-3 
using, 13-6 to 13-9 

w 

WHILE statement, 11-9 
Workspace, 12-7 

defined, 17-1 

optimizing use of, 17-5 

Y 

YACHTS sample domain, 2-2, 2-4 
access all records, 7-2 
comparing records, 7-4 to 7-6 
SET COLUMNS_PAGE command, 
18-2 to 18-4 
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